@melt-inc/buf-json-schema

Protobuf to JSON Schema

Convert Protobuf descriptors to JSON Schema. Powered by Buf.

API

[!WARNING] API is currently in Alpha and is subject to breaking changes.

messageToJSONSchema

messageToJSONSchema(proto: DescriptorProto, descriptors?: DescriptorSet): any

Creates a JSON Schema from the given DescriptorProto. If a DescriptorSet is also given, it will be used to resolve any references to other types.

fileToJSONSchema

fileDescriptorToJSONSchema(proto: FileDescriptorProto, descriptors?: DescriptorSet): any

Creates a JSON Schema from the given FileDescriptorProto. If a DescriptorSet is also given, it will be used to resolve any references to other types. Every message type in the file descriptor will exist in the JSON Schema definitions section, and a oneOf constraint will ensure only one message matches validation. See test for some examples.

Example usage

Getting a descriptor

You can load a descriptor set from binary or JSON.

import { FileDescriptorSet, createDescriptorSet } from "@bufbuild/protobuf";

// load descriptors from file (or anywhere)
const buffer = fs.readFileSync("test/example-descriptors.bin");
const fileDescriptors = FileDescriptorSet.fromBinary(buffer)

// create descriptor set
let descriptorSet = createDescriptorSet(fileDescriptors);

// get message descriptor
let messageDescriptor = descriptorSet.messages.get("mypackage.MyProtoMessage")

Then import proto-json-schema and use the relevant top-level function:

import { messageDescriptor } from "@melt-inc/proto-json-schema"
let schema = messageToJSONSchema(messageDescriptor.proto, descriptorSet)

TypeScript Extension Methods

For convenience, the .toJSONSchema() module augmentation is available on Buf descriptor classes.

import "@melt-inc/proto-json-schema/extensions"

// use extension method              ↓↓↓↓↓↓↓↓↓↓↓↓
let schema = messageDescriptor.proto.toJSONSchema(descriptorSet)

Progress

Currently only a subset of valid protobuf definitions are supported. Track the progress of development below:

• [x] Resolve references from descriptor set
• [x] Message
• [x] File
  • [ ] Tests
• [ ] Enum
• [x] Field
  • [x] Scalar
  • [x] Messages
  • [x] Repeated
    • [ ] Tests
  • [ ] Enum
    • [ ] Tests
  • [ ] Maps
  • [ ] Group (deprecated in proto3)
• [x] Well Known
  • [ ] Any (message)
  • [x] BoolValue (message)
  • [ ] BytesValue (message)
  • [x] DoubleValue (message)
  • [x] Duration (message)
  • [ ] Empty (message)
  • [ ] Enum (message)
  • [ ] EnumValue (message)
  • [ ] FieldMask (message)
  • [x] FloatValue (message)
  • [x] Int32Value (message)
  • [x] Int64Value (message)
  • [x] ListValue (message)
  • [ ] NullValue (enum)
  • [x] StringValue (message)
  • [x] Struct (message)
  • [ ] Timestamp (message)
  • [x] UInt32Value (message)
  • [x] UInt64Value (message)
  • [x] Value (message)
• [ ] Future features
  • [ ] protovalidate / protoc-gen-validate constraints
  • [ ] Descriptions sourced from code comments