Skip to content

Schema checks#

Schema checks are available on Enterprise BSR instances only.

Protobuf schemas are the contract between every producer and every consumer of an API. A single breaking change, pushed without anyone noticing, can take down production for every team that depends on it — and the larger your organization gets, the more unlikely it is that every team has the same buf.yaml config, the same CI checks, or the same review discipline.

Schema checks fix this at the registry layer. An admin turns them on once, and the Buf Schema Registry (BSR) enforces breaking-change, uniqueness, and custom rules on every buf push regardless of what individual teams have configured locally. Pushes that violate policy are either rejected outright or routed through a module-owner review flow, depending on how the BSR instance is configured. The result: consistent governance without consistent discipline, and a single place to audit every schema change across the entire organization.

Schema checks sit alongside, not in place of, the lint and breaking-change settings in buf.yaml. buf lint and buf breaking still run locally against buf.yaml while you work and in CI. Schema checks run on the BSR when the push arrives, and the BSR’s decision wins regardless of what the local config allowed.

What gets checked#

Three kinds of rules can run as schema checks:

  • Breaking changes: blocks .proto changes that would break consumers.
  • Uniqueness: blocks duplicate Protobuf file paths and type names across every module on the BSR instance.
  • Buf check plugins: an extension mechanism for writing custom lint or breaking rules when the built-in rules aren’t enough.

Shared policies bundle any combination of the above into a named, reusable configuration that applies at the instance, organization, or repository level. Policies aren’t a separate kind of check; they’re how you compose, version, and target checks.

How enforcement works#

Every buf push that affects a module’s default label gets evaluated against the checks the BSR instance has enabled. Each resulting commit ends up in one of these states:

  • DISABLED: no checks were evaluated because none were enabled.
  • PASSED: the commit passed every check.
  • PENDING: the commit failed one or more checks and is waiting for review.
  • APPROVED: a reviewer approved the pending commit.
  • REJECTED: a reviewer rejected the pending commit, or the BSR rejected the push automatically.

Which of PENDING and REJECTED applies on a failed push depends on instance settings. By default, failed pushes are rejected outright. Admins can switch to a review flow so failed commits enter PENDING instead and wait for a module owner to approve or reject them.

Review and approval#

Review routes pending commits to module owners, who receive an inbox and email notification, and can approve or reject from the BSR UI. Every decision is logged and visible in the commit history.

See Reviewing commits for how to enable the review flow, who can review, and the admin and reviewer UI.

Effects on downstream consumers#

A commit’s status determines whether downstream consumers can see it.

Any commit pushed after a PENDING commit also enters PENDING, unless it passes every check on its own. If the later commit passes, the earlier PENDING commit is automatically rejected and the passing commit becomes the new default-label head.

On the default label, PENDING and REJECTED commits are withheld from every consumer-facing surface:

  • Not installable from a generated SDK registry unless a consumer pins to the specific commit ID. The “latest” version of a generated SDK tracks the latest PASSED or APPROVED commit on the default label.
  • Not usable in Buf Studio.
  • Not returned by the Reflection API.

Next steps#