Skip to content

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 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:

Syntax
$ curl -fsSL -OJ https://BSR_INSTANCE/gen/archive/MODULE_OWNER/MODULE_NAME/PLUGIN_OWNER/PLUGIN_NAME/REFERENCE.FILE_EXT

# Examples
curl -fsSL -OJ https://buf.build/gen/archive/acme/petapis/bufbuild/protoschema-jsonschema/latest.tar.gz
curl -fsSL -OJ https://buf.build/gen/archive/acme/petapis/bufbuild/protoschema-jsonschema/main.tar.gz
curl -fsSL -OJ https://buf.build/gen/archive/acme/petapis/bufbuild/protoschema-jsonschema/fc19856dc93042e290c9197d39a2beca.tar.gz
curl -fsSL -OJ https://buf.build/gen/archive/acme/petapis/bufbuild/protoschema-jsonschema/v1.2.3-fc19856dc930.1.tar.gz

The URL contains these elements:

  • BSR_INSTANCE is the domain name of your BSR instance. (Default: buf.build)
  • MODULE_OWNER is the owner of the module.
  • MODULE_NAME is the name of the module.
  • PLUGIN_OWNER is the owner of the plugin.
  • PLUGIN_NAME is the name of the plugin.
  • REFERENCE must be one of the following:
    • latest: uses the most recent versions of both the module (on its default label) and the plugin.
    • label name: uses the latest commit for the given label and the most recent plugin version
    • commit ID: uses the explicit BSR 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), and N 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.
  • FILE_EXT is the file extension of the archive. This can be either tar.gz or zip

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 feature is only available 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:

  1. Go to the Archives tab for the module you want to download:

    BSR module archives tab

  2. Choose one of the suggested plugins or search for your desired plugin:

    Archive registry suggested plugins

  3. 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.

    Archive registry download

  4. Copy the URL, or click Download to download the archive.