Archive registry
The Buf Schema Registry allows you to generate and download an archive that contains the output of code generation for a combination of any module and Protobuf plugin, similar to what you would get with generated SDKs. It enables you to transform your pre-validated Protobuf schemas into other formats such as JSON Schema or BigQuery for use in later processing steps. You can use the archive with your native package manager, CI/CD workflows, or data pipelines.
To generate an archive, you can either:
- download from the BSR API directly using
curl
, or - choose a plugin and download from the BSR UI
Download with the BSR API
To download an archive directly from the BSR API using curl
, you need to construct a command with the module,
plugin, and module reference information. These examples use the acme/petapis
module and
bufbuild/protoschema-jsonschema
plugin to generate a tarball:
The URL contains these elements:
remote
is the domain name of your BSR servermoduleOwner
is the owner of the modulemoduleName
is the name of the modulepluginOwner
is the owner of the pluginpluginName
is the name of the pluginreference
must be one of the following:latest
: uses the most recent versions of both the module (on its default label) and the plugin.labelName
: uses the latest commit for the given label and the most recent version of the plugincommitId
: uses the explicit module commit and the most recent plugin version. The commit must be the full module commit name.- a full version reference, in the format
vX.Y.Z-commit.N
. Here,X.Y.Z
represents the plugin version,commit
refers to the module's shortened commit name (12 characters), andN
signifies the plugin revision number. This format is commonly used when you want complete control over generation, allowing you to pin to a specific module commit and plugin version.
fileExtension
is the file extension of the archive. This can be eithertar.gz
orzip
Hitting this endpoint always returns a 302 redirect to the download URL, so clients must handle the redirect independently.
Download with the BSR UI
This information only applies to organizations on the Pro and Enterprise plans.
Like the generated SDKs feature, you can build the download URL in the BSR and extract the archive from there using a plugin picker.
To generate and download an archive from the BSR:
-
Go to the Archive tab for the module you want to download:
-
Choose one of the suggested plugins or search for your desired plugin:
-
When you select the plugin, the BSR generates the archive URL from the latest passed commit and plugin version. Use the dropdown selectors to change the module reference if you want a specific commit, label, or version.
-
Copy the URL, or click Download to download the archive.