Skip to content

Uniqueness check

This feature is only available on the Enterprise plan.

BSR server admins can configure their server to require that all Protobuf file paths and type names remain unique across modules. Enabling this feature causes the BSR to reject any pushes that introduce violations to this rule.

Enabling the server-wide uniqueness check is a three-step process:

  1. Scan your existing modules to check for non-unique identifiers (collisions).
  2. Resolve the collisions and re-push modules to the BSR.
  3. Once there are no remaining collisions, enable the uniqueness check in the Admin panel to prevent new collisions from occurring.

Scan for collisions

The scan checks all modules in your BSR instance.

  1. Go to the Admin panel and select Type uniqueness in the Settings section of the menu. If your BSR domain is https://buf.example.com, then it will be available at https://buf.example.com/admin/uniqueness.

    uniqueness panel overview

  2. Click the link in the Prerequisites section to start the scan, then confirm in the prompt window that appears.

    module scanning modal

The BSR then scans all modules in your BSR instance to create a list of all fully qualified names and .proto file paths. When the scan is complete, you’ll see separate lists of any type and path collisions that exist in your schemas. Each of these needs to be resolved and then re-pushed to the BSR before uniqueness can be enforced across your instance.

type and path collisions panel

Resolve collisions

To resolve these collisions, you need to adjust the colliding type names or paths and make new commits. Our style guide and recommendations on package and file naming can help you determine how to resolve these collisions.

In brief, there are two common ways to resolve collisions:

  1. Rename the package. The best place to start is to ensure that packages are uniquely named. This should resolve almost every collision. To paraphrase our documentation, follow a basic package naming convention of {organization/user}.{purpose}.{version}. So even if there are many instances of Address, User, or other very common names, they’ll be uniquely identifiable by the package they’re in, such as company.inventory.v1.Address or company.register.v1.Address.

  2. Rename files to follow package naming. If you've followed the first step, the next most organic change is to align file names/paths with the packages. For example, if you have a company.inventory.v1.Address message in a file address.proto, move this to the path company/inventory/v1/address.proto.

For more in-depth recommendations, please refer to the style guide.

Enable uniqueness check

Once the prerequisites are met, the feature toggle is enabled.

  1. Go to the Admin panel and select Type uniqueness in the Settings section of the menu.

  2. Click the Enforce unique types and file paths toggle, and press the Update button to apply the change.

    enforcement toggle

The uniqueness check is now enabled for your instance, and any attempted commits that include collisions will be blocked by the BSR.