Schema conversion

Protobuf to JSON Schema

Decode protobuf messages into JSON and use the structured output as a reference for building JSON Schema definitions that match your .proto contracts.

Schema-aware JSON outputField type visibilityReference for JSON Schema drafts

From protobuf contracts to JSON Schema definitions

Teams that expose both protobuf and REST endpoints need a way to keep their validation rules consistent. A decoded protobuf message shows exactly which fields exist, their types, and their nesting — which is the same information a JSON Schema captures. By decoding a sample message here, you get a concrete JSON document and a TypeScript interface that together serve as the blueprint for writing or generating a JSON Schema draft.

This workflow is especially useful when a protobuf service is the source of truth and a JSON Schema needs to mirror it for API gateway validation, OpenAPI specs, or frontend form generation. Instead of manually transcribing field names and types from a .proto file, you can decode a real payload, verify the structure visually, and translate it into a JSON Schema with confidence that the mapping is correct.

How protobuf types translate to JSON Schema types

Protobuf int32, uint32, float, and double all correspond to JSON Schema type number with varying format annotations. String maps directly. Bool maps to boolean. Bytes are typically represented as a Base64-encoded string in JSON, so the JSON Schema type is string with contentEncoding set to base64. Repeated fields become arrays, and nested messages become nested objects with their own properties block.

Oneof, map, and enum types require more care. A protobuf oneof is best expressed in JSON Schema with a oneOf array. A map<string, T> becomes an object with additionalProperties typed to T. Proto enums map to a string enum in JSON Schema if you use the string representation, or integer enum if you use numeric values. Seeing these fields decoded in the JSON and TypeScript tabs makes the translation mechanical rather than guesswork.

Practical tips for maintaining schema parity

The most common drift between protobuf and JSON Schema happens with default values and optional fields. Protobuf 3 does not distinguish between a field set to its default and a field that was never set, while JSON Schema can mark fields as required. Decide upfront whether your JSON Schema should treat default-valued fields as present or absent, and test with payloads that exercise both cases using this decoder.

When schemas evolve, run the updated .proto through this tool and compare the new JSON output against the existing JSON Schema. Added fields appear in the JSON, removed fields disappear, and type changes surface as mismatches. That comparison is faster than diffing .proto files by hand when you need to update a validation layer that lives outside the protobuf ecosystem.

Does this tool output a JSON Schema directly?

It produces the decoded JSON and a TypeScript interface, which together provide the structure and types you need to write or generate a JSON Schema manually or with a secondary tool.

How should I handle protobuf bytes fields in JSON Schema?

Bytes fields decode to Base64 strings in JSON. In your JSON Schema, use type string with contentEncoding set to base64 to match this representation.

What about protobuf map fields?

Map fields decode to JSON objects. In JSON Schema, represent them with type object and additionalProperties typed to the map's value type.

Can I use the TypeScript tab to speed up JSON Schema writing?

Yes. The TypeScript interface shows field names and types in a format that maps almost directly to JSON Schema properties, making it a useful side reference while drafting.

Does this handle protobuf oneof in the JSON output?

Yes. Only the populated branch of a oneof group appears in the decoded JSON. When writing the JSON Schema, use a oneOf constraint to enforce mutual exclusivity.