Protobuf Schema Validator
Parse a .proto file with protobufjs, check JSON against its first message, see the binary size and generate TypeScript types for the JSON form.
The interactive tool loads here when JavaScript runs.
About this toolWhat is the Protobuf Schema Validator?
The Protobuf Schema Validator parses a .proto definition with protobufjs, resolves every type reference, and lists the messages, enums and services it found with their field numbers. A syntax error or a reference to a type that does not exist is reported with protobufjs's own message, including the line number for syntax errors.
Validate JSON checks a JSON object against the first message in the definition using the proto3 JSON mapping: field names may be the original snake_case or lowerCamelCase, 64-bit integers may be strings, enums may be names or numbers. Unknown fields, wrong types and out-of-range int32 values are errors. When the JSON is valid it is encoded to the binary wire format and the result shows its size next to the minified JSON.
Generate TS Types turns the definition into TypeScript interfaces for the JSON form of each message. It does not produce encoder or decoder code; use protoc, buf or protobufjs's pbjs for that.
- Real .proto parsing and type resolution with protobufjs
- Lists messages, nested types, enums, maps, oneofs and services
- proto3 JSON mapping check with clear per-field errors
- Binary encoding size and hex preview of valid messages
- TypeScript interfaces generated from your schema
Updated
How to use the Protobuf Schema Validator
- Click Load Sample Proto & Data, or paste your .proto content into the Proto Definition box.
- Click Validate Proto to parse it. You get the syntax, package and each message, enum and service, or the parser error.
- Put the message you want to test first in the file, paste JSON into the JSON Data box and click Validate JSON.
- Read the errors and notes, plus the encoded binary size and its first bytes in hex.
- Click Generate TS Types and open the TypeScript Types tab to copy interfaces for the JSON shape.
Worked examples
The sample User message
Input
Sample proto and sample JSON (id as "12345", three tags, a nested address)
Output
JSON is valid for message example.User Binary encoding: 105 bytes (minified JSON: 212 bytes)
The binary drops field names and uses varints, so it is about half the size of minified JSON for the same data.
An unknown field
Input
{"id": 5, "nickname": "x"}Output
nickname: User has no field named "nickname" (proto3 JSON parsers reject unknown fields by default)
Fields that are simply missing are fine in proto3 and only listed as notes. A field the schema does not know is an error.
Background and insight
Protocol Buffers were built at Google for internal RPC and storage and open-sourced in 2008. proto3, released in 2016, simplified the language: no required fields, no custom defaults, and every scalar defaults to zero, empty or false. Version 3.15 brought back the optional keyword for fields where you need to tell "not set" apart from zero.
The binary format is a sequence of tagged fields. Each tag is (field_number << 3) | wire_type written as a varint, which is why field numbers 1 to 15 cost one byte and should go to the most frequent fields. The classic example from the protobuf documentation: field 1 set to 150 encodes as 08 96 01. Field names never appear in the binary, so renaming a field is safe and renumbering one is a breaking change.
The JSON mapping has its own rules that trip people up. int64 and uint64 are written as strings because JavaScript numbers cannot hold every 64-bit value exactly, bytes are Base64, and enums are written by name. Strict parsers reject unknown fields, which is why this validator reports them as errors rather than ignoring them.
Common use cases
Checking a .proto before code review
Catch unresolved message types, missing semicolons and duplicate names without installing protoc.
Debugging gRPC-Gateway or Connect JSON
Find out why a JSON request is rejected: a camelCase mismatch, an int64 sent as a number, or an enum spelled wrong.
Estimating payload size
Compare the encoded size of a real message with its JSON form before choosing a format for a high-volume topic.
Typing a front end
Generate TypeScript interfaces for the JSON a gateway returns, with int64 fields typed as string.
Tips and limitations
- Validation uses the first message in the file, including nested ones in declaration order. Move the message you want to test to the top.
- Send int64 and uint64 values as strings in JSON. Numbers above 2^53 lose precision in JavaScript.
- imports such as google/protobuf/timestamp.proto are not fetched. Inline the message definitions you need or remove the import.
- In proto3, a missing field and a field set to its zero value look the same on the wire. Use optional when the difference matters.
- Never reuse a deleted field number. Mark it reserved so nobody does it by accident.
Sources and further reading
- Protocol Buffers: Google's Data Interchange Format, Google Open Source Blog. The 2008 open-source release
- Language Guide (proto 3), Google. proto3 syntax, default values and field numbering
- Encoding, Google. Varints, tags and the 08 96 01 example
- ProtoJSON Format, Google. The JSON mapping: 64-bit integers as strings, bytes as Base64, enums by name
- Application Note: Field Presence, Google. The optional keyword in proto3
Frequently asked questions
How do I validate a .proto file online?
Paste the file into Proto Definition and click Validate Proto. It is parsed with protobufjs and every type reference is resolved, so syntax errors and references to undefined messages or enums are reported. A valid file is summarised with each message's fields and numbers.
Which message is my JSON checked against?
The first message type defined in the file, counting nested messages in the order they appear. The result names the message it used, for example example.User. To test a different message, move its definition above the others.
Why does my int64 field fail as a JSON number?
It does not fail here: integers and decimal strings are both accepted. But the proto3 JSON mapping writes int64 as a string because JavaScript numbers are exact only up to 2^53. Send "9007199254740993" rather than the number to avoid silent rounding.
Should JSON field names be snake_case or camelCase?
Either works when reading. The proto3 JSON mapping prints lowerCamelCase, so postal_code becomes postalCode, but parsers also accept the original field name. The validator accepts both and the generated TypeScript uses camelCase.
Does the TypeScript output include encode and decode functions?
No. It describes the JSON shape of each message and enum. For binary encoding and decoding in TypeScript, generate code with protoc plus ts-proto, with buf, or with protobufjs's pbjs and pbts commands.
Why is protobuf binary smaller than JSON?
It replaces field names with small numeric tags and writes integers as varints, so 150 takes two bytes instead of three characters plus a quoted key. For the sample message the binary is 105 bytes against 212 bytes of minified JSON.
Is there an in-depth guide to the Protobuf Schema Validator?
Yes. “Avro vs Protobuf: Schemas, Encoding and Safe Evolution” covers the background, how it works, common pitfalls and worked examples. Read the full guide.
Related Tools You May Like
Free, in-browser tools that pair well with this one.