Merge pull request #191 from Logofile/sync

Documentation change

Author: Logofile

content/programming-guides/editions.md

@@ -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;
@@ -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());
@@ -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
@@ -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;
@@ -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}