Schema documentation – Overview

When you're sharing schemas across teams, consumers need access to documentation so they can understand and use APIs effectively.

The Buf Schema Registry (BSR) features three types of schema documentation:

• Source code with navigation
• Module documentation (as a README.md file you can include in the module)
• Package documentation (as a code comment above the package declaration in your .proto files)

For generated SDKs, you can also add a getting started guide in addition to their API reference documentation.

Source code documentation

The BSR generates documentation for each module, enabling anyone to view the module's .proto files in with an organized UI and navigate easily between them. It also allows schema publishers to add module and package information to provide additional context and usage details.

To view the documentation for any BSR module, go to its Docs tab:

To click around an example, see the connectrpc/eliza module.

Diff schemas

You can do a diff of the schema between any two commits or labels in a BSR repository:

1. Go to the repository's Commits tab and click the Compare button.
2. Choose the labels or enter the commit IDs you want to compare.
3. The BSR displays the diff for each file in the module, including the README and LICENSE.

Module documentation

When you first go to the module documentation, there are links into each of its packages, and any module documentation that the schema owner has provided.

Add a README

Most documentation comes directly from Protobuf comments, but you should also describe your modules so others can understand their functionality.

To create module documentation, add a README.md file and push it to the BSR along with your Protobuf files. If you already have a README.md and want to have a different documentation file for the BSR than your source control, name the file buf.md instead. When both files are present, the BSR displays buf.md instead of README.md.

Because documentation is part of your module, any updates to either README.md or buf.md create new commits in the BSR. You can put the documentation at either the module level or the workspace root. Modules within the workspace without their own documentation fall back to the workspace README.md file.

In this example, the module at proto/weatherapi displays its own README.md file, and the module at proto/units displays the workspace README.md file.

Directory structure

workspace_root
├─ buf.yaml
├─ proto
│  └─ weatherapi
│     ├─ README.md # Module-level documentation
│     ├─ acme
│     │  ├─ weatherapi
│     │  └─ v1
│     │     ├─ api.proto
│     │     └─ calculate.proto
│     └─ units
│        └─ acme
│           ├─ units
│           └─ v1
│              ├─ imperial.proto
│              └─ metric.proto
└─ README.md  # Workspace-level documentation

buf.yaml

version: v2
modules:
  - path: proto/weatherapi
    name: "buf.build/acme/weatherapi"
  - path: proto/units
    name: "buf.build/acme/units"

Package documentation

When you click into a package, you see the package docs at the top, an index of the entities categorized by field type on the left, and the entities themselves in the same order on the right:

Clicking in the index takes you to the referenced item, and you can quickly navigate from the docs to the Protobuf file by clicking the filename on the right side of each entity. Each entity's header also has a unique anchor tag that you can click to copy, enabling you to share a link to the exact item.

Add a package overview

When sharing packages, it's useful to provide an overview of the package. You can do so by adding comments above the package directive in your .proto files:

pet.proto

syntax = "proto3";

// This package represents all information needed to represent a pet for sale in the store.
package pet.v1;

Comments on the package directive aren't merged across files. Files are parsed alphabetically, and only the first file with a non-empty comment is displayed in the generated documentation.

Annotated Protobuf options

The BSR renders annotated Protobuf options in source code style. For the deprecated option, it also displays a notice in the header of each deprecated entity:

The complete list of Protobuf's built-in options is available in the descriptor.proto specification. The list below includes all Protobuf options that the BSR renders documentation for when annotated.

• Message options - deprecated
• Field options
  • deprecated
  • packed
  • ctype
  • jstype
  • lazy
  • unverified_lazy
  • weak
  • uninterpreted_option
• Enum options
  • allow_alias
  • deprecated
  • uninterpreted_option
• EnumValue options
  • deprecated
  • uninterpreted_option
• Service options
  • deprecated
  • uninterpreted_option
• Method options
  • deprecated
  • idempotency_level
  • uninterpreted_option

Custom options

Custom options are also supported and rendered in the generated documentation. The official Protobuf docs show how to create and apply custom options in your .proto file — the sample below shows the .proto file and the resulting documentation:

main/options/v1/options.proto

syntax = "proto3";

package main.options.v1;

extend google.protobuf.EnumValueOptions {
  string country_code_abbrv = 2000;
}

enum CountryCode {
  COUNTRY_CODE_UNSPECIFIED = 0;
  COUNTRY_CODE_INDIA = 1 [(country_code_abbrv) = "IND"];
  COUNTRY_CODE_UNITED_KINGDOM = 2 [(country_code_abbrv) = "GBR"];
  COUNTRY_CODE_UNITED_STATE_OF_AMERICA = 3 [(country_code_abbrv) = "USA"];
}

Formatting syntax

The module documentation and package documentation, including Protobuf type definitions and comments, support the following syntax for formatting.

• CommonMark: Standardized, common features of Markdown.
• GitHub Flavored Markdown: Markdown extension developed by GitHub, including additional features like task lists and tables.
• Mermaid: Tool for diagramming and charting. Start the code block with ```mermaid.