Uniqueness check
This feature is only available on the Enterprise plan.
BSR administrators can configure their instances 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 instance-wide uniqueness check is a three-step process:
- Scan your existing modules to check for non-unique identifiers (collisions).
- Resolve the collisions and re-push modules to the BSR.
- 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.
-
Go to the Admin panel and select Type uniqueness in the Settings section of the menu. If your BSR instance is
https://buf.example.com
, it's available athttps://buf.example.com/admin/uniqueness
. -
Click the link in the Prerequisites section to start the scan, then confirm in the prompt window that appears.
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.
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:
-
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 ofAddress
,User
, or other common names, they’ll be uniquely identifiable by the package they’re in, such ascompany.inventory.v1.Address
orcompany.register.v1.Address
. -
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 fileaddress.proto
, move this to the pathcompany/inventory/v1/address.proto
.
For more in-depth recommendations, refer to the style guide.
Enable uniqueness check
Once the prerequisites are met, the feature toggle is enabled.
- Go to the Admin panel and select Type uniqueness in the Settings section of the menu.
-
Click the Enforce unique types and file paths toggle, and press the Update button to apply the change.
The uniqueness check is now enabled for your instance, and the BSR blocks any attempted commits that include collisions.