Home

Awesome

Protobuf to JSON-Schema compiler

This takes protobuf definitions and converts them into JSONSchemas, which can be used to dynamically validate JSON messages.

Useful for people who define their data using ProtoBuf, but use JSON for the "wire" format.

"Heavily influenced" by Google's protobuf-to-BigQuery-schema compiler.

Generated Schemas

Logic

Installation

Note: This tool requires Go 1.11+ to be installed.

Install this plugin using Go:

go install github.com/chrusty/protoc-gen-jsonschema/cmd/protoc-gen-jsonschema@latest

Usage

Note: This plugin requires the protoc CLI to be installed.

protoc-gen-jsonschema is designed to run like any other proto generator. The following examples show how to use options flags to enable different generator behaviours (more examples in the Makefile too).

protoc \ # The protobuf compiler
--jsonschema_out=. \ # jsonschema out directory
--proto_path=testdata/proto testdata/proto/ArrayOfPrimitives.proto # proto input directories and folders

Configuration Parameters

The following configuration parameters are supported. They should be added to the protoc command and can be combined as a comma-delimited string. Some examples are included in the following Examples section.

Options can also be provided in this format (which is easier on the eye):

protoc \
  --plugin=${HOME}/go/bin/protoc-gen-jsonschema \
  --jsonschema_opt=enforce_oneof
  --jsonschema_opt=file_extension=schema.json \
  --jsonschema_opt=disallow_additional_properties \
  --jsonschema_out=schemas \
  --proto_path=proto
CONFIGDESCRIPTION
all_fields_requiredRequire all fields in schema
allow_null_valuesAllow null values in schema
debugEnable debug logging
disallow_additional_propertiesDisallow additional properties in schema
disallow_bigints_as_stringsDisallow big integers as strings
enforce_oneofInterpret Proto "oneOf" clauses
enums_as_strings_onlyOnly include strings in the allowed values for enums
file_extensionSpecify a custom file extension for generated schemas
json_fieldnamesUse JSON field names only
prefix_schema_files_with_packagePrefix the output filename with package
proto_and_json_fieldnamesUse proto and JSON field names
type_names_with_no_packageWhen generating type names and refs, do not include the full package in the type name

Custom Proto Options

If you don't want to use the configuration parameters (admittedly quite a nasty cli syntax) then some of the generator behaviour can be controlled using custom proto options. These are defined in options.proto, and your protoc command will need to include this file. See the sample protos and generator commands in the Makefile.

Enum Options

These apply to specifically marked enums, giving you more finely-grained control than with the CLI flags.

Field Options

These apply to specifically marked fields, giving you more finely-grained control than with the CLI flags.

File Options

These options apply to an entire proto file.

Message Options

These options apply to a specific proto message.

Validation Options

We are also beginning to support validation options from protoc-gen-validate.

At the moment the following are supported (but export more in the future):

Examples

Require all fields

Because proto3 doesn't accommodate this.

protoc \
--jsonschema_out=all_fields_required:. \
--proto_path=testdata/proto testdata/proto/ArrayOfPrimitives.proto

Allow NULL values

By default, JSONSchemas will reject NULL values unless we explicitly allow them

protoc \
--jsonschema_out=allow_null_values:. \
--proto_path=testdata/proto testdata/proto/ArrayOfPrimitives.proto

Enable debug logging

protoc \
--jsonschema_out=debug:. \
--proto_path=testdata/proto testdata/proto/ArrayOfPrimitives.proto

Disallow additional properties

JSONSchemas won't validate JSON containing extra parameters

protoc \
--jsonschema_out=disallow_additional_properties:. \
--proto_path=testdata/proto testdata/proto/ArrayOfPrimitives.proto

Disallow permissive validation of big-integers as strings

(eg scientific notation)

protoc \
--jsonschema_out=disallow_bigints_as_strings:. \
--proto_path=testdata/proto testdata/proto/ArrayOfPrimitives.proto

Prefix generated schema files with their package name (as a directory)

protoc \
--jsonschema_out=prefix_schema_files_with_package:. \
--proto_path=testdata/proto testdata/proto/ArrayOfPrimitives.proto

Target specific messages within a proto file

# Generates MessageKind10.jsonschema and MessageKind11.jsonschema
# Use this to generate json schema from proto files with multiple messages
# Separate schema names with '+'
protoc \
--jsonschema_out=messages=[MessageKind10+MessageKind11]:. \
--proto_path=testdata/proto testdata/proto/TwelveMessages.proto

Generate fields with JSON names

protoc \
--jsonschema_out=json_fieldnames:. \
--proto_path=testdata/proto testdata/proto/ArrayOfPrimitives.proto

Custom schema file extension

The default file extension is json. You can override that with the "file_extension" parameter.

protoc \
--jsonschema_out=file_extension=jsonschema:. \
--proto_path=internal/converter/testdata/proto internal/converter/testdata/proto/ArrayOfPrimitives.proto

Generate type names without fully qualified package

By default, referenced type names will be generated using the fully qualified package and type name. e.g packageName.TypeName. Setting this option will generate type names and their references only as TypeName

protoc \
--jsonschema_out=type_names_with_no_package:. \
--proto_path=internal/converter/testdata/proto internal/converter/testdata/proto/ArrayOfPrimitives.proto

Sample protos (for testing)

Links