How to use the json to protobuf converter
- Paste a valid JSON object into the JSON input text area.
- Optionally change the Root message name to suit your domain model.
- The proto3 schema appears automatically as you type or paste.
- Copy the generated
.protodefinition into your project or use it withprotoc.
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 type | Proto3 type | Notes |
|---|---|---|
| String | string | UTF-8 encoded, supports Unicode characters |
| Integer number | int64 | Whole numbers without a decimal point |
| Floating-point number | double | Numbers containing a decimal point or exponent |
| Boolean | bool | true or false |
| Object | Nested message | Generates a child message with PascalCase name |
| Array | repeated T | Type T inferred from all elements |
| Null | bytes | No 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 bytessince 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
messageorservice), the generated schema may require manual adjustment.
Worked examples
| Example | Input | Result |
|---|---|---|
| Simple user object | JSON input: {"name":"Ada","age":36,"active":true}; Root message name: User | syntax = "proto3"; / message User { / bool active = 1; / int64 age = 2; / string name = 3; / } |
| Nested object with array | JSON input: {"id":1,"tags":["admin","user"],"address":{"city":"Berlin","zip":"10115"}}; Root message name: Account | syntax = "proto3"; / message Address { / string city = 1; / string zip = 2; / } / message Account { / Address address = 1; / int64 id = 2; / repeated string tags = 3; / } |
| Mixed-type array | JSON input: {"data":[1,"two",true,null]}; Root message name: Mixed | syntax = "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.