{"id":15102793,"url":"https://github.com/bufbuild/protoschema-plugins","last_synced_at":"2025-10-22T22:31:46.346Z","repository":{"id":227518163,"uuid":"771646712","full_name":"bufbuild/protoschema-plugins","owner":"bufbuild","description":"Protobuf plugins that generate various schemas from protobuf files - JSON Schema, PubSub, etc.","archived":false,"fork":false,"pushed_at":"2025-02-03T17:02:14.000Z","size":524,"stargazers_count":25,"open_issues_count":6,"forks_count":3,"subscribers_count":11,"default_branch":"main","last_synced_at":"2025-02-03T17:46:42.466Z","etag":null,"topics":["buf-cli","buf-schema-registry","jsonschema","protobuf","protoc","protocol-buffers","pubsub"],"latest_commit_sha":null,"homepage":"https://buf.build","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bufbuild.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-03-13T17:24:53.000Z","updated_at":"2025-02-03T17:01:10.000Z","dependencies_parsed_at":"2024-06-21T12:58:38.395Z","dependency_job_id":"86c13b80-86db-4b7d-8ef2-09e67d91c051","html_url":"https://github.com/bufbuild/protoschema-plugins","commit_stats":{"total_commits":16,"total_committers":6,"mean_commits":"2.6666666666666665","dds":0.5625,"last_synced_commit":"587beba97a7616dd591700cb636f0e0030e2855f"},"previous_names":["bufbuild/protoschema-plugins"],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bufbuild%2Fprotoschema-plugins","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bufbuild%2Fprotoschema-plugins/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bufbuild%2Fprotoschema-plugins/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bufbuild%2Fprotoschema-plugins/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bufbuild","download_url":"https://codeload.github.com/bufbuild/protoschema-plugins/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":237748110,"owners_count":19359777,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["buf-cli","buf-schema-registry","jsonschema","protobuf","protoc","protocol-buffers","pubsub"],"created_at":"2024-09-25T19:06:56.658Z","updated_at":"2025-10-22T22:31:46.340Z","avatar_url":"https://github.com/bufbuild.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# protoschema-plugins\n\n[![Build](https://github.com/bufbuild/protoschema-plugins/actions/workflows/ci.yaml/badge.svg?branch=main)][badges_ci]\n[![Report Card](https://goreportcard.com/badge/github.com/bufbuild/protoschema-plugins)][badges_goreportcard]\n[![GoDoc](https://pkg.go.dev/badge/github.com/bufbuild/protoschema-plugins.svg)][badges_godoc]\n[![Slack](https://img.shields.io/badge/slack-buf-%23e01563)][badges_slack]\n\nThe protoschema-plugins repository contains a collection of Protobuf plugins that generate different\ntypes of schema from protobuf files. This includes:\n\n- [PubSub](#pubsub-protobuf-schema)\n- [JSON Schema](#json-schema)\n\n## PubSub Protobuf Schema\n\nGenerates a schema for a given protobuf file that can be used as a PubSub schema in the form of a\nsingle self-contained messaged normalized to proto2.\n\nInstall the `protoc-gen-pubsub` plugin directly:\n\n```sh\ngo install github.com/bufbuild/protoschema-plugins/cmd/protoc-gen-pubsub@latest\n```\n\nOr reference it as a [Remote Plugin](https://buf.build/docs/generate/remote-plugins) in `buf.gen.yaml`:\n\n```yaml\nversion: v1\nplugins:\n  - plugin: buf.build/bufbuild/protoschema-pubsub\n    out: ./gen\n```\n\nFor examples see [testdata](/internal/testdata/pubsub/) which contains the generated schema for\ntest case definitions found in [proto](/internal/proto/).\n\n## JSON Schema\n\nGenerates a [JSON Schema](https://json-schema.org/) for a given protobuf file. This implementation\nuses the latest [JSON Schema Draft 2020-12](https://json-schema.org/draft/2020-12/release-notes).\n\nInstall the `protoc-gen-jsonschema` directly:\n\n```sh\ngo install github.com/bufbuild/protoschema-plugins/cmd/protoc-gen-jsonschema@latest\n```\n\nOr reference it as a [Remote Plugin](https://buf.build/docs/generate/remote-plugins) in `buf.gen.yaml`:\n\n```yaml\nversion: v1\nplugins:\n  - plugin: buf.build/bufbuild/protoschema-jsonschema\n    out: ./gen\n```\n\nFor examples see [testdata](/internal/testdata/jsonschema/) which contains the generated schema for\ntest case definitions found in [proto](/internal/proto/).\n\nHere is a simple generated schema from the following protobuf:\n\n```proto\n// A product.\n//\n// A product is a good or service that is offered for sale.\nmessage Product {\n  // A point on the earth's surface.\n  message Location {\n    double lat = 1 [\n      (buf.validate.field).double.finite = true,\n      (buf.validate.field).double.gte = -90,\n      (buf.validate.field).double.lte = 90\n    ];\n    double long = 2 [\n      (buf.validate.field).double.finite = true,\n      (buf.validate.field).double.gte = -180,\n      (buf.validate.field).double.lte = 180\n    ];\n  }\n\n  // The unique identifier for the product.\n  int32 product_id = 1 [(buf.validate.field).required = true];\n  // The name of the product.\n  string product_name = 2 [(buf.validate.field).required = true];\n  // The price of the product.\n  float price = 3 [\n    (buf.validate.field).float.finite = true,\n    (buf.validate.field).float.gte = 0\n  ];\n  // The tags associated with the product.\n  repeated string tags = 4;\n  // The location of the product.\n  Location location = 5 [(buf.validate.field).required = true];\n}\n\n```\n\nBy default, results in the following JSON Schema files:\n\n- `*.schema.json` files are generated with protobuf field names (e.g. `product_id`, `product_name`)\n- `*.schema.bundle.json` files include all dependencies in a single file with protobuf field names.\n- `*.schema.strict.json` files are generated with protobuf field names, but do not allow aliases, string numbers, or any other non-normalized representation.\n- `*.schema.strict.bundle.json` files include the strict schema with all dependencies in a single file with protobuf field names.\n- `*.jsonschema.json` files are generated with JSON field names (e.g. `productId`, `productName`)\n  other non-normalized representation.\n- `*.jsonschema.bundle.json` files include all dependencies in a single file with the JSON field names.\n- `*.jsonschema.strict.json` files are generated with JSON field names, but do not allow aliases, string numbers, or any other non-normalized representation.\n- `*.jsonschema.strict.bundle.json` files include the strict JSON schema with all dependencies in a single file with JSON field names.\n\nFor example, the above protobuf generates the following `*.schema.json` files:\n\n\u003cdetails\u003e\n\u003csummary\u003eProduct.schema.json\u003c/summary\u003e\n\n```json\n{\n  \"$id\": \"Product.schema.json\",\n  \"$schema\": \"https://json-schema.org/draft/2020-12/schema\",\n  \"additionalProperties\": false,\n  \"title\": \"A product.\",\n  \"description\": \"A product is a good or service that is offered for sale.\",\n  \"type\": \"object\",\n  \"properties\": {\n    \"product_id\": {\n      \"description\": \"The unique identifier for the product.\",\n      \"maximum\": 2147483647,\n      \"minimum\": -2147483648,\n      \"type\": \"integer\"\n    },\n    \"product_name\": {\n      \"description\": \"The name of the product.\",\n      \"type\": \"string\"\n    },\n    \"price\": {\n      \"anyOf\": [\n        {\n          \"maximum\": 3.4028234663852886e38,\n          \"minimum\": 0,\n          \"type\": \"number\"\n        },\n        {\n          \"pattern\": \"^-?[0-9]+(\\\\.[0-9]+)?([eE][+-]?[0-9]+)?$\",\n          \"type\": \"string\"\n        }\n      ],\n      \"default\": 0,\n      \"description\": \"The price of the product.\"\n    },\n    \"tags\": {\n      \"description\": \"The tags associated with the product.\",\n      \"items\": {\n        \"type\": \"string\"\n      },\n      \"type\": \"array\"\n    },\n    \"location\": {\n      \"$ref\": \"Product.Location.schema.json\",\n      \"description\": \"The location of the product.\"\n    }\n  },\n  \"required\": [\"product_id\", \"product_name\", \"location\"],\n  \"patternProperties\": {\n    \"^(productId)$\": {\n      \"description\": \"The unique identifier for the product.\",\n      \"maximum\": 2147483647,\n      \"minimum\": -2147483648,\n      \"type\": \"integer\"\n    },\n    \"^(productName)$\": {\n      \"description\": \"The name of the product.\",\n      \"type\": \"string\"\n    }\n  }\n}\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eProduct.Location.schema.json\u003c/summary\u003e\n\n```json\n{\n  \"$id\": \"Location.schema.json\",\n  \"$schema\": \"https://json-schema.org/draft/2020-12/schema\",\n  \"additionalProperties\": false,\n  \"title\": \"Location\",\n  \"description\": \"A point on the earth's surface.\",\n  \"type\": \"object\",\n  \"properties\": {\n    \"lat\": {\n      \"anyOf\": [\n        {\n          \"maximum\": 90,\n          \"minimum\": -90,\n          \"type\": \"number\"\n        },\n        {\n          \"pattern\": \"^-?[0-9]+(\\\\.[0-9]+)?([eE][+-]?[0-9]+)?$\",\n          \"type\": \"string\"\n        }\n      ],\n      \"default\": 0\n    },\n    \"long\": {\n      \"anyOf\": [\n        {\n          \"maximum\": 180,\n          \"minimum\": -180,\n          \"type\": \"number\"\n        },\n        {\n          \"pattern\": \"^-?[0-9]+(\\\\.[0-9]+)?([eE][+-]?[0-9]+)?$\",\n          \"type\": \"string\"\n        }\n      ],\n      \"default\": 0\n    }\n  }\n}\n```\n\n\u003c/details\u003e\n\nOr the following `*.jsonschema.strict.bundle.json` file:\n\n\u003cdetails\u003e\n\u003csummary\u003eProduct.jsonschema.strict.bundle.json\u003c/summary\u003e\n\n```json\n{\n  \"$schema\": \"https://json-schema.org/draft/2020-12/schema\",\n  \"$id\": \"buf.protoschema.test.v1.Product.jsonschema.strict.bundle.json\",\n  \"$ref\": \"#/$defs/buf.protoschema.test.v1.Product.jsonschema.strict.json\",\n  \"$defs\": {\n    \"buf.protoschema.test.v1.Product.jsonschema.strict.json\": {\n      \"$schema\": \"https://json-schema.org/draft/2020-12/schema\",\n      \"title\": \"A product.\",\n      \"description\": \"A product is a good or service that is offered for sale.\",\n      \"type\": \"object\",\n      \"properties\": {\n        \"productId\": {\n          \"description\": \"The unique identifier for the product.\",\n          \"maximum\": 2147483647,\n          \"minimum\": -2147483648,\n          \"type\": \"integer\"\n        },\n        \"productName\": {\n          \"description\": \"The name of the product.\",\n          \"type\": \"string\"\n        },\n        \"price\": {\n          \"description\": \"The price of the product.\",\n          \"maximum\": 3.4028234663852886e38,\n          \"minimum\": 0,\n          \"type\": \"number\"\n        },\n        \"tags\": {\n          \"description\": \"The tags associated with the product.\",\n          \"items\": {\n            \"type\": \"string\"\n          },\n          \"type\": \"array\"\n        },\n        \"location\": {\n          \"$ref\": \"#/$defs/buf.protoschema.test.v1.Product.Location.jsonschema.strict.json\",\n          \"description\": \"The location of the product.\"\n        }\n      },\n      \"required\": [\"productId\", \"productName\", \"price\", \"location\"],\n      \"additionalProperties\": false\n    },\n    \"buf.protoschema.test.v1.Product.Location.jsonschema.strict.json\": {\n      \"$schema\": \"https://json-schema.org/draft/2020-12/schema\",\n      \"additionalProperties\": true,\n      \"description\": \"A point on the earth's surface.\",\n      \"properties\": {\n        \"lat\": {\n          \"maximum\": 90,\n          \"minimum\": -90,\n          \"type\": \"number\"\n        },\n        \"long\": {\n          \"maximum\": 180,\n          \"minimum\": -180,\n          \"type\": \"number\"\n        }\n      },\n      \"required\": [\"lat\", \"long\"],\n      \"title\": \"Location\",\n      \"type\": \"object\"\n    }\n  }\n}\n```\n\n\u003c/details\u003e\n\n### Options\n\nThe JSON Schema plugin supports the following options:\n\n- `target` - Any of `proto`, `json`, `proto-bundle`, `json-bundle`, `proto-strict`, `json-strict`,\n  `proto-strict-bundle`, `json-strict-bundle`, or `all` separated by `+` (e.g. `proto+json`). Defaults to `all`.\n  - If `proto`, the schema will be generated with Protobuf field names (e.g. `product_id`,\n    `product_name`).\n  - If `json`, the schema will be generated with JSON field names (e.g. `productId`, `productName`).\n  - If suffixed with `-bundle`, the schema will include all dependencies in a single file.\n  - If suffixed with `-strict`, the schema will not allow aliases, string numbers, or any other\n    non-normalized representation. Strict is useful when the validated JSON data is used directly\n    instead of being converted to a Protobuf message. Requires the \"always emit fields without\n    presence\" option when using [Protobuf JSON](https://protobuf.dev/programming-guides/json/#json-options).\n  - If suffixed with `-strict-bundle`, the schema will be strict and include all dependencies in a single file.\n- `additional_properties` - If `true`, the generated schema will set `additionalProperties` to\n  `true`, causing unknown fields to be ignored instead of erroring. Defaults to `false`. Useful when a\n  client/sender may have a different version the schema than the server/receiver. Similar to the\n  \"ignore unknown fields\" option in [Protobuf JSON](https://protobuf.dev/programming-guides/json/#json-options).\n\n## Community\n\nFor help and discussion around Protobuf, best practices, and more, join us\non [Slack][badges_slack].\n\n## Status\n\nThis project is currently in **alpha**. The API should be considered unstable and likely to change.\n\n## Legal\n\nOffered under the [Apache 2 license][license].\n\n[badges_ci]: https://github.com/bufbuild/protoschema-plugins/actions/workflows/ci.yaml\n[badges_goreportcard]: https://goreportcard.com/report/github.com/bufbuild/protoschema-plugins\n[badges_godoc]: https://pkg.go.dev/github.com/bufbuild/protoschema-plugins\n[badges_slack]: https://join.slack.com/t/bufbuild/shared_invite/zt-f5k547ki-dW9LjSwEnl6qTzbyZtPojw\n[license]: https://github.com/bufbuild/protoschema-plugins/blob/main/LICENSE.txt\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbufbuild%2Fprotoschema-plugins","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbufbuild%2Fprotoschema-plugins","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbufbuild%2Fprotoschema-plugins/lists"}