Skip to content

Uniqueness check#

This feature is only available on the Enterprise plan.

The BSR's unique type names and file paths checks allows you to enforce that a particular Protobuf type name or file path is only contained within one module across your instance. This enables features such as server reflection, allowing you to uniquely resolve Protobuf types and files across your entire BSR instance. This page describes how to enable and disable the unique type names and file paths check on your private BSR instance. You must be a BSR administrator to access these settings.

This check is enabled by default.

How it works#

When the uniqueness check is enabled, the BSR checks that all Protobuf file paths and type names are unique across modules in your BSR instance. Only schemas pushed to the default label are checked for uniqueness. Some modules are exempt from this check.

Pushes that fail this check do not enter the review flow.

Disabling the uniqueness check#

This feature can be disabled by an admin, allowing multiple modules to contain the same type names or file paths.

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

  2. In the Unique types and paths section, turn the Enforce unique types and file paths toggle off, and press the Update button to apply the change.

    enforcement toggle

The uniqueness check is now disabled for your instance, and the BSR no longer blocks any attempted commits that include collisions.

Enabling the uniqueness check#

If you previously disabled the uniqueness check, or if your instance was created before the uniqueness check was enabled by default, you can enable it in the Admin panel. Setting up the instance-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, except for some modules.

  1. Go to the Admin panel and select Checks in the Settings section of the menu. If your BSR instance is https://buf.example.com, it's available at https://buf.example.com/admin/checks.

    uniqueness panel overview

  2. In the Unique types and filepaths section, 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][style-guide] and recommendations on [package][package-recommendations] and [file naming][file-recommendations] 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 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, refer to the [style guide][style-guide].

Enable uniqueness check#

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

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

  2. In the Unique types and paths section, 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 the BSR blocks any attempted commits that include collisions.

Modules exempt from this check#

When checking for unique file paths and type names, the BSR ignores the Buf-managed modules, given that their sources aren't managed by Buf or by BSR administrators or users. This allows BSR users to have their own copies of any of those modules, and/or reuse some of those file paths. The BSR does report collisions across 2 or more user-managed modules, even if those file paths or type names are also present in the Buf-managed modules.