Skip to content

Documentation change #191

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Oct 25, 2024
Merged

Documentation change #191

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f0c5f35
This documentation changes includes the following:
Oct 16, 2024
63e87b5
This documentation change includes the following:
Oct 25, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
230 changes: 9 additions & 221 deletions content/programming-guides/editions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1356,7 +1356,7 @@ and unpack `Any` values in a typesafe manner – for example, in Java, the `Any`
type will have special `pack()` and `unpack()` accessors, while in C++ there are
`PackFrom()` and `UnpackTo()` methods:

```c++
```cpp
// Storing an arbitrary message type in Any.
NetworkErrorDetails details = ...;
ErrorStatus status;
Expand Down Expand Up @@ -1425,7 +1425,7 @@ language in the relevant [API reference](/reference/).
oneof. So if you set several oneof fields, only the *last* field you set
will still have a value.

```c++
```cpp
SampleMessage message;
message.set_name("name");
CHECK(message.has_name());
Expand All @@ -1452,7 +1452,7 @@ language in the relevant [API reference](/reference/).
following sample code will crash because `sub_message` was already deleted
by calling the `set_name()` method.

```c++
```cpp
SampleMessage message;
SubMessage* sub_message = message.mutable_sub_message();
message.set_name("name"); // Will delete sub_message
Expand All @@ -1463,7 +1463,7 @@ language in the relevant [API reference](/reference/).
end up with the other's oneof case: in the example below, `msg1` will have a
`sub_message` and `msg2` will have a `name`.

```c++
```cpp
SampleMessage msg1;
msg1.set_name("name");
SampleMessage msg2;
Expand Down Expand Up @@ -1644,223 +1644,11 @@ about, see the

## JSON Mapping {#json}

Protobuf supports a canonical encoding in JSON, making it easier to share data
between systems. The encoding is described on a type-by-type basis in the table
below.

When parsing JSON-encoded data into a protocol buffer, if a value is missing or
if its value is `null`, it will be interpreted as the corresponding
[default value](#default).

When generating JSON-encoded output from a protocol buffer, if a protobuf field
has the default value and if the field doesn't support field presence, it will
be omitted from the output by default. An implementation may provide options to
include fields with default values in the output.

Singular fields that have a value set and that support field presence always
include the field value in the JSON-encoded output, even if it is the default
value.

<table>
<tbody>
<tr>
<th>Editions</th>
<th>JSON</th>
<th>JSON example</th>
<th>Notes</th>
</tr>
<tr>
<td>message</td>
<td>object</td>
<td><code>{"fooBar": v, "g": null, ...}</code></td>
<td>Generates JSON objects. Message field names are mapped to
lowerCamelCase and become JSON object keys. If the
<code>json_name</code> field option is specified, the specified value
will be used as the key instead. Parsers accept both the lowerCamelCase
name (or the one specified by the <code>json_name</code> option) and the
original proto field name. <code>null</code> is an accepted value for
all field types and treated as the default value of the corresponding
field type. However, <code>null</code> cannot be used for the
<code>json_name</code> value. For more on why, see
<a href="/news/2023-04-28#json-name">Stricter validation for json_name</a>.
</td>
</tr>
<tr>
<td>enum</td>
<td>string</td>
<td><code>"FOO_BAR"</code></td>
<td>The name of the enum value as specified in proto is used. Parsers
accept both enum names and integer values.
</td>
</tr>
<tr>
<td>map&lt;K,V&gt;</td>
<td>object</td>
<td><code>{"k": v, ...}</code></td>
<td>All keys are converted to strings.</td>
</tr>
<tr>
<td>repeated V</td>
<td>array</td>
<td><code>[v, ...]</code></td>
<td><code>null</code> is accepted as the empty list <code>[]</code>.</td>
</tr>
<tr>
<td>bool</td>
<td>true, false</td>
<td><code>true, false</code></td>
<td></td>
</tr>
<tr>
<td>string</td>
<td>string</td>
<td><code>"Hello World!"</code></td>
<td></td>
</tr>
<tr>
<td>bytes</td>
<td>base64 string</td>
<td><code>"YWJjMTIzIT8kKiYoKSctPUB+"</code></td>
<td>JSON value will be the data encoded as a string using standard base64
encoding with paddings. Either standard or URL-safe base64 encoding
with/without paddings are accepted.
</td>
</tr>
<tr>
<td>int32, fixed32, uint32</td>
<td>number</td>
<td><code>1, -10, 0</code></td>
<td>JSON value will be a decimal number. Either numbers or strings are
accepted. Empty strings are invalid.
</td>
</tr>
<tr>
<td>int64, fixed64, uint64</td>
<td>string</td>
<td><code>"1", "-10"</code></td>
<td>JSON value will be a decimal string. Either numbers or strings are
accepted. Empty strings are invalid.
</td>
</tr>
<tr>
<td>float, double</td>
<td>number</td>
<td><code>1.1, -10.0, 0, "NaN", "Infinity"</code></td>
<td>JSON value will be a number or one of the special string values "NaN",
"Infinity", and "-Infinity". Either numbers or strings are accepted.
Empty strings are invalid. Exponent notation is also accepted.
</td>
</tr>
<tr>
<td>Any</td>
<td><code>object</code></td>
<td><code>{"@type": "url", "f": v, ... }</code></td>
<td>If the <code>Any</code> contains a value that has a special JSON
mapping, it will be converted as follows: <code>{"@type": xxx, "value":
yyy}</code>. Otherwise, the value will be converted into a JSON object,
and the <code>"@type"</code> field will be inserted to indicate the
actual data type.
</td>
</tr>
<tr>
<td>Timestamp</td>
<td>string</td>
<td><code>"1972-01-01T10:00:20.021Z"</code></td>
<td>Uses RFC 3339, where generated output will always be Z-normalized
and uses 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are
also accepted.
</td>
</tr>
<tr>
<td>Duration</td>
<td>string</td>
<td><code>"1.000340012s", "1s"</code></td>
<td>Generated output always contains 0, 3, 6, or 9 fractional digits,
depending on required precision, followed by the suffix "s". Accepted
are any fractional digits (also none) as long as they fit into
nano-seconds precision and the suffix "s" is required.
</td>
</tr>
<tr>
<td>Struct</td>
<td><code>object</code></td>
<td><code>{ ... }</code></td>
<td>Any JSON object. See <code>struct.proto</code>.</td>
</tr>
<tr>
<td>Wrapper types</td>
<td>various types</td>
<td><code>2, "2", "foo", true, "true", null, 0, ...</code></td>
<td>Wrappers use the same representation in JSON as the wrapped primitive
type, except that <code>null</code> is allowed and preserved during data
conversion and transfer.
</td>
</tr>
<tr>
<td>FieldMask</td>
<td>string</td>
<td><code>"f.fooBar,h"</code></td>
<td>See <code>field_mask.proto</code>.</td>
</tr>
<tr>
<td>ListValue</td>
<td>array</td>
<td><code>[foo, bar, ...]</code></td>
<td></td>
</tr>
<tr>
<td>Value</td>
<td>value</td>
<td></td>
<td>Any JSON value. Check
<a href="/reference/protobuf/google.protobuf#value">google.protobuf.Value</a>
for details.
</td>
</tr>
<tr>
<td>NullValue</td>
<td>null</td>
<td></td>
<td>JSON null</td>
</tr>
<tr>
<td>Empty</td>
<td>object</td>
<td><code>{}</code></td>
<td>An empty JSON object</td>
</tr>
</tbody>
</table>

### JSON Options {#json-options}

A protobuf JSON implementation may provide the following options:

* **Always emit fields without presence**: Fields that don't support presence
and that have their default value are omitted by default in JSON output (for
example, an implicit presence integer with a 0 value, implicit presence
string fields that are empty strings, and empty repeated and map fields). An
implementation may provide an option to override this behavior and output
fields with their default values.

As of v25.x, the C++, Java, and Python implementations are nonconformant, as
this flag affects proto2 `optional` fields but not proto3 `optional` fields.
A fix is planned for a future release.

* **Ignore unknown fields**: The protobuf JSON parser should reject unknown
fields by default but may provide an option to ignore unknown fields in
parsing.

* **Use proto field name instead of lowerCamelCase name**: By default the
protobuf JSON printer should convert the field name to lowerCamelCase and
use that as the JSON name. An implementation may provide an option to use
proto field name as the JSON name instead. Protobuf JSON parsers are
required to accept both the converted lowerCamelCase name and the proto
field name.

* **Emit enum values as integers instead of strings**: The name of an enum
value is used by default in JSON output. An option may be provided to use
the numeric value of the enum value instead.
The standard protobuf binary wire format is the preferred serialization format
for communication between two systems that use protobufs. For communicating with
systems that use JSON rather than protobuf wire format, Protobuf supports a
canonical encoding in
[ProtoJSON](/programming-guides/json).

## Options {#options}

Expand Down
Loading
Loading