Xerobit

JSON to Protobuf Schema Converter

Paste a JSON object to instantly generate a Protocol Buffers (proto3) schema. The converter infers field types from values, creates nested messages for objects, marks arrays as repeated, and sorts keys alphabetically for deterministic output. It runs entirely in the browser so nothing is uploaded.

A valid JSON object. Arrays, nested objects, nulls and Unicode are supported.

Proto3 Schema

syntax = "proto3";

message RootMessage {
  bool active = 1;
  int64 age = 2;
  string name = 3;
}

How to use the json to protobuf converter

  1. Paste a valid JSON object into the JSON input text area.
  2. Optionally change the Root message name to suit your domain model.
  3. The proto3 schema appears automatically as you type or paste.
  4. Copy the generated .proto definition into your project or use it with protoc.

How the conversion works

The converter walks the JSON tree depth-first. For each key it inspects the value type and maps it to a proto3 scalar: strings become string, booleans become bool, and numbers become double if they contain a decimal point or int64 if they are whole integers. Null values map to bytes because proto3 has no native null type.

Nested JSON objects trigger the creation of a new child message. The child message name is derived by converting the field name to PascalCase. Arrays are marked with the repeated keyword, and the element type is inferred from all items, so objects are merged into one message. If an array contains mixed types, the converter falls back to bytes. Arrays of arrays get a small wrapper message, because proto3 does not allow repeated repeated. Scalar fields that are null or missing in some objects of a merged array are marked optional.

For example, given {"age": 30, "name": "Ada"}, the tool produces:

syntax = "proto3";
message RootMessage {
  int64 age = 1;
  string name = 2;
}

Type mapping reference

This table shows how each JSON type translates to a Protocol Buffers type during the json to protobuf conversion.

JSON typeProto3 typeNotes
StringstringUTF-8 encoded, supports Unicode characters
Integer numberint64Whole numbers without a decimal point
Floating-point numberdoubleNumbers containing a decimal point or exponent
Booleanbooltrue or false
ObjectNested messageGenerates a child message with PascalCase name
Arrayrepeated TType T inferred from all elements
NullbytesNo native null in proto3; bytes used as placeholder

Deterministic output and stable key order

Protocol Buffers assign a unique integer tag to every field. Changing the order of fields between versions can break compatibility if tags shift. To prevent this, the converter sorts all keys alphabetically before assigning sequential tags starting at 1. This means running the same JSON through the tool always produces identical output, which is essential for version control and code review.

If you need to preserve a specific field order or assign custom tags, edit the generated schema after conversion. The alphabetical sort guarantees stability, not semantic ordering.

Handling edge cases

Real-world JSON often contains quirks that require careful handling when generating a protobuf schema:

  • Empty objects: An empty object {} generates a message with no fields.
  • Empty arrays: An array with no elements defaults to repeated bytes since there is no value to infer a type from.
  • Mixed-type arrays: If an array contains both strings and numbers, the converter cannot pick a single proto3 type and falls back to repeated bytes.
  • Unicode: Proto3 strings are UTF-8 by specification, so emoji and non-Latin scripts pass through without modification.
  • Reserved words: If a JSON key matches a proto3 reserved word (like message or service), the generated schema may require manual adjustment.

Worked examples

ExampleInputResult
Simple user objectJSON input: {"name":"Ada","age":36,"active":true}; Root message name: Usersyntax = "proto3"; / message User { / bool active = 1; / int64 age = 2; / string name = 3; / }
Nested object with arrayJSON input: {"id":1,"tags":["admin","user"],"address":{"city":"Berlin","zip":"10115"}}; Root message name: Accountsyntax = "proto3"; / message Address { / string city = 1; / string zip = 2; / } / message Account { / Address address = 1; / int64 id = 2; / repeated string tags = 3; / }
Mixed-type arrayJSON input: {"data":[1,"two",true,null]}; Root message name: Mixedsyntax = "proto3"; / message Mixed { / repeated bytes data = 1; // mixed types / }

FAQ

What is Protocol Buffers?

Protocol Buffers (protobuf) is a language-neutral, platform-neutral mechanism for serializing structured data developed by Google. A .proto file defines message types and their fields, which compilers then use to generate code in various languages.

Why does null become bytes?

Proto3 does not have a native null type. Scalar fields default to zero or empty string. Using bytes as a placeholder signals that the original JSON value was explicitly null, allowing downstream code to handle it appropriately.

Can I use the generated schema directly with protoc?

Yes, the output includes the required syntax declaration and valid message definitions. You may need to adjust field names if they conflict with proto3 reserved keywords or add package declarations for your project.

Are field tags stable across runs?

Yes. The converter sorts keys alphabetically before assigning sequential integer tags starting at 1. Providing the same JSON input will always produce the same tags, ensuring deterministic output.

Does this work with JSON arrays at the root level?

No. A valid proto3 schema requires a root message, so the input must be a JSON object. If your data is an array, wrap it in an object like {"items": [...]} before converting.

Is my data sent to a server?

No. The json to protobuf conversion happens entirely in your browser using JavaScript. Nothing is uploaded or transmitted over the network.