JSON in Protobuf — eine .proto für protoc

Was dieses Werkzeug tut

Aus einer JSON-Probe werden proto3-Messages, eines je Objekt.

{ "id": 1, "name": "Ada", "tags": ["admin"], "address": { "city": "Paris" } }

syntax = "proto3";

message Root {
  int64 id = 1;
  string name = 2;
  repeated string tags = 3;
  Address address = 4;
}

message Address {
  string city = 1;
}

Die Feldnummern beginnen in jedem Message bei 1, in der Reihenfolge der Schlüssel. Sie sind es, was protobuf über die Leitung schickt: Namen sind für Menschen, Nummern sind der Vertrag.

Der ursprüngliche Schlüssel bleibt

Ein protobuf-Feldname schreibt sich nach Konvention [a-z_][a-z0-9_]* und verträgt keinen Bindestrich. content-type wird also content_type — und hier beißt es: proto3s JSON-Abbildung leitet den JSON-Schlüssel aus dem Feldnamen ab, in lowerCamelCase. content_type wird zu contentType, was nicht der Schlüssel Ihrer Daten ist.

string content_type = 1 [json_name = "content-type"];

json_name hält den ursprünglichen Schlüssel fest, und das Message liest weiter das Dokument, aus dem es entstand. Die Option erscheint nur, wenn die Reparatur etwas verändert hat: ein Schlüssel in snake_case braucht sie nicht, denn ein proto3-Parser nimmt den Feldnamen auch unverändert an.

Das war ein echter Fehler: das erzeugte .proto passte stillschweigend nicht mehr zu seiner eigenen Eingabe. Beim Schreiben dieser Seite gefunden und behoben.

64-Bit-Ganzzahlen reisen als Zeichenketten

Ganzzahlen werden int64. In proto3s JSON-Abbildung wird int64 als Zeichenkette kodiert:

{ "id": "12345678901" }

Das ist die Spezifikation, keine Wahl von hier — JSON-Zahlen tragen 64 Bit nicht gefahrlos, also umgeht die Abbildung sie. Es heißt aber, dass eine Runde durch protobuf den Typ ändert, den Ihr Verbraucher sieht. Ist das Feld ein kleiner Zähler, lohnt der Wechsel zu int32.

Was proto3 nicht sagen kann, sagt es mit Value

• null und unbekannte Werte werden google.protobuf.Value, und import "google/protobuf/struct.proto" kommt dazu — nur wenn etwas es braucht.
• Ein verschachteltes Array wird google.protobuf.ListValue: proto3 verbietet repeated repeated, ein Array von Arrays hat also keine direkte Form.
• Ein gemischtes Array wird repeated google.protobuf.Value, außer es mischt Ganzzahlen und Fließkommazahlen: dann deckt repeated double beide ab.

Präsenz ist nicht, was man erwartet

In proto3 hat ein skalares Feld ohne das Schlüsselwort optional keine Präsenz: nach dem Dekodieren sind ein fehlendes Feld und ein Feld mit 0, "" oder false nicht zu unterscheiden. Nichts in einer JSON-Probe sagt, welche Schlüssel wirklich optional sind, also wird hier nichts als optional markiert. Wo der Unterschied zählt — eine nullbare Note, ein ungesetztes Flag — ist das Schlüsselwort die passende Änderung.

Datenschutz ab Werk

Alles läuft lokal in deinem Browser mit JavaScript. Deine Daten werden nie hochgeladen, wodurch das Tool auch für sensible Inhalte sicher ist und offline funktioniert.