JSON a Protobuf — un .proto que protoc compila

Qué hace esta herramienta

Una muestra JSON pasa a ser mensajes proto3, uno por objeto.

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

Los números de campo empiezan en 1 en cada mensaje, en el orden en que aparecieron las claves. Son ellos los que protobuf pone en el cable: los nombres son para las personas, los números son el contrato.

La clave original se conserva

Un nombre de campo de protobuf se escribe por convención [a-z_][a-z0-9_]* y no admite guion. content-type pasa por tanto a content_type, y aquí está lo que muerde: el mapeo JSON de proto3 deriva la clave JSON del nombre de campo, en lowerCamelCase. content_type se convierte en contentType, que no es la clave de tus datos.

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

json_name fija la clave original, y el mensaje vuelve a leer el documento del que salió. La opción se emite solo si la reparación cambió algo: una clave ya en snake_case no la necesita, porque un analizador proto3 acepta también el nombre de campo tal cual.

Era un defecto real: el .proto generado dejaba en silencio de casar con su propia entrada. Encontrado al escribir esta página y corregido.

Los enteros de 64 bits viajan como cadenas

Los enteros pasan a int64. En el mapeo JSON de proto3, int64 se codifica como cadena:

{ "id": "12345678901" }

Es la especificación, no una elección de aquí: los números JSON no llevan 64 bits sin riesgo y el mapeo los esquiva. Significa que una vuelta por protobuf cambia el tipo que ve tu consumidor. Si el campo es un contador pequeño, pasar a int32 es un retoque justificado.

Lo que proto3 no sabe decir, lo dice con Value

• null y los valores desconocidos pasan a google.protobuf.Value, y se añade import "google/protobuf/struct.proto", solo si algo lo necesita.
• Un array anidado pasa a google.protobuf.ListValue: proto3 prohíbe repeated repeated, así que un array de arrays no tiene forma directa.
• Un array heterogéneo pasa a repeated google.protobuf.Value, salvo si mezcla enteros y flotantes: entonces repeated double cubre ambos.

La presencia no es lo que parece

En proto3, un campo escalar sin la palabra optional no tiene presencia: tras decodificar, un campo ausente y un campo a 0, "" o false son indistinguibles. Nada en una muestra JSON dice qué claves son realmente opcionales, así que aquí nada se marca optional. Donde la diferencia importe —una nota anulable, una bandera sin fijar—, añadir la palabra es el retoque a hacer.

Privado por diseño

Todo se ejecuta localmente en tu navegador con JavaScript. Tus datos nunca se suben a un servidor, lo que hace que la herramienta sea segura para contenido sensible y funcione sin conexión.