JSON to Protobuf — proto3 Messages, Field Numbers, Zero Upload

Real-world use cases

• Bootstrap a gRPC service contract from an existing JSON API

  You're migrating a REST endpoint to gRPC and need the `.proto` to match what the JSON already returns. Curl the endpoint once, paste the response, name the root `GetUserResponse`, and copy the output into `user.proto`. The nested `address` object lifts out as `GetUserResponseAddress`, the `roles` array becomes `repeated string`, and field numbers are pre-assigned so you can run `protoc` immediately and tune numbers before anything ships.

• Reverse-engineer a third-party webhook into a typed message

  A vendor sends webhooks as JSON with no schema published. Log a few payloads, paste a representative one, and you get a `message` you can deserialize into instead of poking at `map[string]interface{}`. Where one payload has a field another lacks, the union is captured in one folded message, so a single `.proto` covers the variations you've actually observed.

• Generate a Kafka / event-bus message definition

  Your team standardised on protobuf for the event bus but the producer still emits JSON during prototyping. Paste a sample event, set the `package` to `events.v1`, and get a clean message with `int64` timestamps and `repeated` item lists. Drop it in the schema registry, and consumers in Go, Java, and Rust all generate matching types from the same `.proto`.

• Compare proto3 vs proto2 output before committing to a syntax

  You inherited a proto2 codebase and want to see how a new payload looks in both syntaxes. Paste the JSON, flip the syntax toggle, and watch proto2 add explicit `optional` labels while proto3 stays terse. Decide which fits your toolchain, then turn on proto3 `optional` only for the fields where distinguishing "unset" from "zero" actually matters.

• Document an undocumented internal payload as a schema

  A legacy service passes around a fat JSON blob with no contract. Paste a real example, name the root after the message, and the generated `.proto` becomes living documentation: every field typed, every nested object named, every array marked `repeated`. Check it into the repo so the next engineer reads a schema instead of guessing from `json.loads`.

Common pitfalls

• Treating the generated field numbers as final. Numbers are assigned in JSON key order, but on the wire the NUMBER is the contract — once shipped you can rename a field freely but never reuse or reorder a number. Review the numbering before production and add `reserved` ranges for fields you plan to add.

• Expecting int32 / uint32 for small or unsigned IDs. JSON gives no width or sign, so every integer infers as `int64` — the safe superset that holds ms timestamps and snowflake IDs. Narrow to `int32` / `uint32` / `uint64` by hand only when you know the real domain; a JSON `-1` would break an unsigned type.

• Assuming a single object reveals optional fields. proto3 has no required/optional at the wire level, and a single object has no missing-key signal, so every field is plain singular. To see how optional/union fields fold, paste an array of objects (`[{...},{...}]`) where some elements carry a key and others don't.

• Pasting JSON5 / JSON-with-comments / trailing commas. We use strict `JSON.parse`, so comments, unquoted keys, and trailing commas all error out. Strip them first, or run the input through a JSON formatter as a pre-step.

Privacy