Proto3 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.
Proto3支持JSON中的規(guī)范編碼，使得在系統(tǒng)間分享數(shù)據(jù)變得簡單。下表中描述了基于逐個類型的編碼。
If a value is missing in the JSON-encoded data or if its value is null, it will be interpreted as the appropriate default value when parsed into a protocol buffer. If a field has the default value in the protocol buffer, it will be omitted in the JSON-encoded data by default to save space. An implementation may provide options to emit fields with default values in the JSON-encoded output.
如果JSON編碼數(shù)據(jù)中缺少一個值或者其值是null，在解析為protocol buffer時這會被解析為合適的默認值。protocol buffer中如果一個字段有默認值，為了節(jié)省空間JSON編碼數(shù)據(jù)中會默認將其省略掉。實現(xiàn)可以提供選項以在 JSON 編碼的輸出中發(fā)出具有默認值的字段。
| proto3 | JSON | JSON example | Notes |
|---|---|---|---|
| message | object | <code translate="no" dir="ltr">{"fooBar": v,<wbr> "g": null,<wbr> …}</code> | Generates JSON objects. Message field names are mapped to lowerCamelCase and become JSON object keys. If the <code translate="no" dir="ltr">json_<wbr>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 translate="no" dir="ltr">json_<wbr>name</code> option) and the original proto field name. <code translate="no" dir="ltr">null</code> is an accepted value for all field types and treated as the default value of the corresponding field type. |
| enum | string | <code translate="no" dir="ltr">"FOO_<wbr>BAR"</code> | The name of the enum value as specified in proto is used. Parsers accept both enum names and integer values. |
| map<K,V> | object | <code translate="no" dir="ltr">{"k": v,<wbr> …}</code> | All keys are converted to strings. |
| repeated V | array | <code translate="no" dir="ltr">[v,<wbr> …]</code> | <code translate="no" dir="ltr">null</code> is accepted as the empty list <code translate="no" dir="ltr">[]</code>. |
| bool | true, false | <code translate="no" dir="ltr">true,<wbr> false</code> | |
| string | string | <code translate="no" dir="ltr">"Hello World!"</code> | |
| bytes | base64 string | <code translate="no" dir="ltr">"YWJjMTIzIT8kKiYoKSctPUB+"</code> | 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. |
| int32, fixed32, uint32 | number | <code translate="no" dir="ltr">1,<wbr> -10,<wbr> 0</code> | JSON value will be a decimal number. Either numbers or strings are accepted. |
| int64, fixed64, uint64 | string | <code translate="no" dir="ltr">"1",<wbr> "-10"</code> | JSON value will be a decimal string. Either numbers or strings are accepted. |
| float, double | number | <code translate="no" dir="ltr">1.<wbr>1,<wbr> -10.<wbr>0,<wbr> 0,<wbr> "NaN",<wbr> "Infinity"</code> | JSON value will be a number or one of the special string values "NaN", "Infinity", and "-Infinity". Either numbers or strings are accepted. Exponent notation is also accepted. -0 is considered equivalent to 0. |
| Any | <code translate="no" dir="ltr">object</code> | <code translate="no" dir="ltr">{"@type": "url",<wbr> "f": v,<wbr> … }</code> | If the <code translate="no" dir="ltr">Any</code> contains a value that has a special JSON mapping, it will be converted as follows: <code translate="no" dir="ltr">{"@type": xxx,<wbr> "value": yyy}</code>. Otherwise, the value will be converted into a JSON object, and the <code translate="no" dir="ltr">"@type"</code> field will be inserted to indicate the actual data type. |
| Timestamp | string | <code translate="no" dir="ltr">"1972-01-01T10:00:20.<wbr>021Z"</code> | 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. |
| Duration | string | <code translate="no" dir="ltr">"1.<wbr>000340012s",<wbr> "1s"</code> | 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. |
| Struct | <code translate="no" dir="ltr">object</code> | <code translate="no" dir="ltr">{ … }</code> | Any JSON object. See <code translate="no" dir="ltr">struct.<wbr>proto</code>. |
| Wrapper types | various types | <code translate="no" dir="ltr">2,<wbr> "2",<wbr> "foo",<wbr> true,<wbr> "true",<wbr> null,<wbr> 0,<wbr> …</code> | Wrappers use the same representation in JSON as the wrapped primitive type, except that <code translate="no" dir="ltr">null</code> is allowed and preserved during data conversion and transfer. |
| FieldMask | string | <code translate="no" dir="ltr">"f.<wbr>fooBar,<wbr>h"</code> | See <code translate="no" dir="ltr">field_<wbr>mask.<wbr>proto</code>. |
| ListValue | array | <code translate="no" dir="ltr">[foo,<wbr> bar,<wbr> …]</code> | |
| Value | value | Any JSON value. Check <a href="/protocol-buffers/docs/reference/google.protobuf#google.protobuf.Value">google.protobuf.Value</a> for details. | |
| NullValue | null | JSON null | |
| Empty | object | <code translate="no" dir="ltr">{}</code> | An empty JSON object |
JSON options - JSON選項
A proto3 JSON implementation may provide the following options:
一個proto3 JSON實現(xiàn)可以提供如下選項：
Emit fields with default values: Fields with default values are omitted by default in proto3 JSON output. An implementation may provide an option to override this behavior and output fields with their default values.
發(fā)出有默認值的字段：在proto3 JSON輸出中，默認值的字段會默認被省略掉。實現(xiàn)可以提供一個選項來覆蓋這種表現(xiàn)并使用默認值來輸出該字段。Ignore unknown fields: Proto3 JSON parser should reject unknown fields by default but may provide an option to ignore unknown fields in parsing.
忽略未知字段：Proto3 JSON解析器默認拒絕未知字段，但是可以提供一個選項在解析是來忽略未知字段。Use proto field name instead of lowerCamelCase name: By default proto3 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. Proto3 JSON parsers are required to accept both the converted lowerCamelCase name and the proto field name.
使用proto 字段命名而不是駝峰命令：proto3 JSON打印器應該默認將字段名稱轉換為駝峰命名來用作JSON命名。實現(xiàn)可以提供一個選項使用proto 字段作為JSON命名。要求Proto3 JSON解析器可接受駝峰和proto 字段兩種命名。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.
將枚舉值作為整數(shù)而不是字符串發(fā)出：JSON輸出中默認使用枚舉值的名稱?？梢蕴峁┮粋€選項來代替使用枚舉值的數(shù)值。
