ProtoJSON形式
Protobuf は JSON での正規エンコーディングをサポートしており、標準の protobuf バイナリワイヤーフォーマットをサポートしないシステムとのデータ共有を容易にします。
ProtoJSON形式は protobuf ワイヤーフォーマットほど効率的ではありません。コンバーターはメッセージのエンコードとデコードにより多くの CPU を使用し、（まれなケースを除き）エンコードされたメッセージはより多くのスペースを消費します。さらに、ProtoJSON形式はフィールド名と enum 値名をエンコードされたメッセージに入れるため、後でこれらの名前を変更することが非常に困難になります。フィールドを削除すると、解析エラーを引き起こす破壊的な変更になります。要するに、Google が ProtoJSON 形式ではなく、事実上すべてのものに標準のワイヤーフォーマットを使用することを好む理由はたくさんあります。
エンコーディングについては、このトピックの後半の表でタイプごとに説明します。
JSON エンコードされたデータをプロトコルバッファーに解析する際、値が欠落している場合、または値が null の場合、対応する デフォルト値 として解釈されます。
プロトコルバッファーから JSON エンコードされた出力を生成する際、protobuf フィールドがデフォルト値を持ち、フィールドがフィールドのプレゼンスをサポートしていない場合、デフォルトで出力から省略されます。実装によっては、デフォルト値を持つフィールドを出力に含めるオプションが提供される場合があります。
値が設定され、フィールドのプレゼンスをサポートするフィールドは、デフォルト値であっても、常に JSON エンコードされた出力にフィールド値を含めます。たとえば、optional キーワードで定義された proto3 フィールドはフィールドのプレゼンスをサポートしており、設定されている場合は常に JSON 出力に表示されます。protobuf の任意のエディションのメッセージタイプフィールドはフィールドのプレゼンスをサポートしており、設定されている場合は出力に表示されます。Proto3 の暗黙的なプレゼンスを持つスカラーフィールドは、そのタイプのデフォルト値に設定されていない場合にのみ JSON 出力に表示されます。
| Protobuf | JSON | JSON の例 | 注記 |
|---|---|---|---|
| message | object | {"fooBar": v, "g": null, ...} | JSON オブジェクトを生成します。メッセージフィールド名は lowerCamelCase にマップされ、JSON オブジェクトキーになります。json_name フィールドオプションが指定されている場合、指定された値がキーとして代わりに使用されます。パーサーは、lowerCamelCase 名 (または json_name オプションで指定された名前) と元の proto フィールド名の両方を受け入れます。null はすべてのフィールドタイプで受け入れられる値であり、対応するフィールドタイプのデフォルト値として扱われます。ただし、null は json_name 値には使用できません。理由の詳細については、json_name の厳格な検証 を参照してください。 |
| enum | string | "FOO_BAR" | proto で指定された enum 値の名前が使用されます。パーサーは enum 名と整数値の両方を受け入れます。 |
| map<K,V> | object | {"k": v, ...} | すべてのキーは文字列に変換されます。 |
| repeated V | array | [v, ...] | null は空のリスト [] として受け入れられます。 |
| bool | true, false | true, false | |
| string | string | "Hello World!" | |
| bytes | base64 string | "YWJjMTIzIT8kKiYoKSctPUB+" | JSON 値は、パディング付きの標準 base64 エンコーディングを使用して文字列としてエンコードされたデータになります。標準または URL セーフ base64 エンコーディング（パディングの有無にかかわらず）のいずれかが受け入れられます。 |
| int32, fixed32, uint32 | number | 1, -10, 0 | JSON 値は 10 進数になります。数値または文字列のいずれかが受け入れられます。空の文字列は無効です。 |
| int64, fixed64, uint64 | string | "1", "-10" | JSON 値は 10 進文字列になります。数値または文字列のいずれかが受け入れられます。空の文字列は無効です。 |
| float, double | number | 1.1, -10.0, 0, "NaN", "Infinity" | JSON 値は、数値または特別な文字列値 "NaN"、"Infinity"、および "-Infinity" のいずれかになります。数値または文字列のいずれかが受け入れられます。空の文字列は無効です。指数表記も受け入れられます。 |
| Any | object | {"@type": "url", "f": v, ... } | Any に特別な JSON マッピングを持つ値が含まれている場合、次のように変換されます: {"@type": xxx, "value": yyy}。それ以外の場合、値は JSON オブジェクトに変換され、実際のデータ型を示すために "@type" フィールドが挿入されます。 |
| Timestamp | string | "1972-01-01T10:00:20.021Z" | RFC 3339 を使用します。生成された出力は常に Z 正規化され、0、3、6、または 9 桁の小数部を使用します。"Z" 以外のオフセットも受け入れられます。 |
| Duration | string | "1.000340012s", "1s" | 生成された出力には、必要な精度に応じて、常に 0、3、6、または 9 桁の小数部が含まれ、その後にサフィックス "s" が続きます。ナノ秒の精度に収まる限り、任意の小数部 (なしも可) が受け入れられ、サフィックス "s" が必要です。 |
| Struct | object | { ... } | 任意の JSON オブジェクト。struct.proto を参照してください。 |
| Wrapper types | various types | 2, "2", "foo", true, "true", null, 0, ... | ラッパーは、JSON でラップされたプリミティブ型と同じ表現を使用しますが、null が許可され、データ変換と転送中に保持される点が異なります。 |
| FieldMask | string | "f.fooBar,h" | field_mask.proto を参照してください。 |
| ListValue | array | [foo, bar, ...] | |
| Value | value | 任意の JSON 値。詳細については、google.protobuf.Value を確認してください。 | |
| NullValue | null | JSON null | |
| Empty | object | {} | 空の JSON オブジェクト |
JSONオプション
準拠する protobuf JSON 実装は、次のオプションを提供できます
常にプレゼンスなしでフィールドを出力する: プレゼンスをサポートせず、デフォルト値を持つフィールドは、JSON 出力ではデフォルトで省略されます (例: 値が 0 の暗黙的なプレゼンスを持つ整数、空の文字列である暗黙的なプレゼンスを持つ文字列フィールド、および空の repeated フィールドと map フィールド)。実装によっては、この動作をオーバーライドし、デフォルト値を持つフィールドを出力するオプションが提供される場合があります。
v25.x の時点では、C++、Java、および Python の実装はこのフラグが proto2
optionalフィールドには影響するが、proto3optionalフィールドには影響しないため、非準拠です。将来のリリースで修正が計画されています。不明なフィールドを無視する: protobuf JSON パーサーは、デフォルトで不明なフィールドを拒否する必要がありますが、解析時に不明なフィールドを無視するオプションを提供できます。
lowerCamelCase 名の代わりに proto フィールド名を使用する: デフォルトでは、protobuf JSON プリンターはフィールド名を lowerCamelCase に変換し、それを JSON 名として使用する必要があります。実装によっては、代わりに proto フィールド名を JSON 名として使用するオプションを提供できます。Protobuf JSON パーサーは、変換された lowerCamelCase 名と proto フィールド名の両方を受け入れる必要があります。
enum 値を文字列の代わりに整数として出力する: enum 値の名前は、JSON 出力でデフォルトで使用されます。代わりに enum 値の数値を使用するオプションが提供される場合があります。