JSON in Protobuf — un .proto che protoc compila

Che cosa fa questo strumento

Un campione JSON diventa messaggi proto3, uno per oggetto.

{ "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;
}

I numeri dei campi partono da 1 in ogni messaggio, nell’ordine in cui le chiavi sono comparse. Sono loro che protobuf mette sul filo: i nomi sono per le persone, i numeri sono il contratto.

La chiave originale è conservata

Un nome di campo protobuf si scrive per convenzione [a-z_][a-z0-9_]* e non ammette trattini. content-type diventa quindi content_type — ed ecco ciò che morde: la mappatura JSON di proto3 ricava la chiave JSON dal nome del campo, in lowerCamelCase. content_type diventa contentType, che non è la chiave dei tuoi dati.

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

json_name fissa la chiave originale, e il messaggio rilegge il documento da cui è nato. L’opzione è emessa solo se la riparazione ha cambiato qualcosa: una chiave già in snake_case non ne ha bisogno, perché un analizzatore proto3 accetta anche il nome del campo così com’è.

Era un difetto vero: il .proto generato smetteva in silenzio di corrispondere al proprio ingresso. Trovato scrivendo questa pagina e corretto.

Gli interi a 64 bit viaggiano come stringhe

Gli interi diventano int64. Nella mappatura JSON di proto3, int64 è codificato come stringa:

{ "id": "12345678901" }

È la specifica, non una scelta di qui — i numeri JSON non reggono 64 bit senza rischio, e la mappatura li evita. Significa però che un giro per protobuf cambia il tipo che vede chi consuma. Se il campo è un piccolo contatore, passare a int32 è una modifica sensata.

Ciò che proto3 non sa dire, lo dice con Value

• null e i valori ignoti diventano google.protobuf.Value, e viene aggiunto import "google/protobuf/struct.proto" — solo se qualcosa lo richiede.
• Un array annidato diventa google.protobuf.ListValue: proto3 vieta repeated repeated, quindi un array di array non ha forma diretta.
• Un array eterogeneo diventa repeated google.protobuf.Value, salvo quando mescola interi e decimali: lì repeated double copre entrambi.

La presenza non è quella che ti aspetti

In proto3 un campo scalare senza la parola optional non ha presenza: dopo la decodifica, un campo assente e un campo a 0, "" o false sono indistinguibili. Nulla in un campione JSON dice quali chiavi siano davvero opzionali, quindi qui nulla è segnato optional. Dove la differenza conta — un punteggio annullabile, un flag non impostato — aggiungere la parola è la modifica da fare.

Privato per progettazione

Tutto viene eseguito localmente nel browser con JavaScript. I tuoi dati non vengono mai caricati, quindi lo strumento è sicuro per contenuti sensibili e funziona anche offline.