Skip to content

Download an archive#

For plugins that aren't compatible with package managers, you can download an archive containing generated code for any Protobuf plugin supported by the BSR. This allows you to transform your pre-validated Protobuf schemas into other formats, such as JSON Schema or BigQuery. You can also use archives with CI/CD workflows or data pipelines.

To generate an archive, you can either:

For plugins that are compatible with package managers, we recommend installing the generated SDK for a better user experience. The archive download link doesn't appear in the BSR for them, but if you prefer an archive, you can use the curl commands below.

Download from the BSR web app#

To download an archive from the web app:

  1. Go to the module you want and click the SDKs tab.
  2. Choose the plugin for the SDK.
  3. If desired, change the plugin version and/or module label by using the dropdowns, the same as for a generated SDK above.
  4. Click Download archive at the top right of the SDK section, choose the archive format, and click Download or copy the URL to use with curl.

Download with the BSR API#

To download an archive using the BSR API and curl, you need to construct a command with the module, plugin, and reference information. 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.
    • A label name: Uses the latest commit for the given label and the most recent plugin version.
    • A commit ID: Uses the explicit BSR module commit and the most recent plugin version. The commit must be the full module commit name.
  • 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.

Syntax for latest version of plugin
$ curl -fsSL -O https://BSR_INSTANCE/gen/archive/MODULE_OWNER/MODULE_NAME/PLUGIN_OWNER/PLUGIN_NAME/REFERENCE.FILE_EXT

# Get latest version of module's default label
$ curl -fsSL -O https://buf.build/gen/archive/connectrpc/eliza/bufbuild/protoschema-jsonschema/latest.zip

# Get latest version of specific module label ('demo')
$ curl -fsSL -O https://buf.build/gen/archive/connectrpc/eliza/bufbuild/protoschema-jsonschema/demo.zip

# Get specific module commit
$ curl -fsSL -O https://buf.build/gen/archive/connectrpc/eliza/bufbuild/protoschema-jsonschema/8bde2b90ec0a7f23df3de5824bed0b6ea2043305.zip

You can also set the imports and wkt parameters to include the module's imports and/or the Well Known Types. This behaves the same as applying the --include_imports and --include_wkt flags to buf generate at the command line or setting them in buf.gen.yaml. Both flags must be set to include the Well Known Types.

Syntax for imports and Well Known Types
$ curl -fsSL -O "https://buf.build/gen/archive/connectrpc/eliza/bufbuild/protoschema-jsonschema/latest.zip?imports=true&wkt=true"

Specific plugin version and module commit#

If you need to pin the archive to a specific plugin version and module commit, the curl syntax changes slightly. The latest and label name references aren't available in this case, so you must specify the reference in the format vX.Y.Z-commit.N:

  • X.Y.Z and N are the plugin version and revision number respectively, which you can view in the sample URL on the SDK's installation page.
  • commit is the shortened 12-character module commit name.
Syntax for specific plugin version and module commit
$ curl -fsSL -O https://BSR_INSTANCE/gen/archive/MODULE_OWNER/MODULE_NAME/PLUGIN_OWNER/PLUGIN_NAME/vX.Y.Z-commit.N.FILE_EXT

# Get specific module commit and plugin version
$ curl -fsSL -O https://buf.build/gen/archive/connectrpc/eliza/bufbuild/protoschema-jsonschema/v0.5.0-233fca715f49.1.zip
$ curl -fsSL -O "https://buf.build/gen/archive/connectrpc/eliza/bufbuild/protoschema-jsonschema/v0.5.0-233fca715f49.1.zip?imports=true"
$ curl -fsSL -O "https://buf.build/gen/archive/connectrpc/eliza/bufbuild/protoschema-jsonschema/v0.5.0-233fca715f49.1.zip?imports=true&wkt=true"

Access individual files#

In addition to serving an archive in a packaged format, the BSR serves the raw contents of each archive. Users can access these hosted files by specifying a subpath relative to the basename of the archive.

Syntax for referencing a file from an archive
https://BSR_INSTANCE/gen/archive/MODULE_OWNER/MODULE_NAME/PLUGIN_OWNER/PLUGIN_NAME/raw/REFERENCE/FILE_PATH

Referencing JSON schema files#

This allows users to reference individual JSON Schema files in archives generated using the protoschema-jsonschema plugin.

Syntax for referencing a JSON Schema file from an archive
https://buf.build/gen/archive/connectrpc/eliza/bufbuild/protoschema-jsonschema/raw/latest/connectrpc.eliza.v1.ConverseRequest.schema.json

This allows tools like IDEs to provide functionality, like auto-completion within YAML files, based on an associated JSON Schema:

Use JSON Schema to provide auto-completion for code editors
yaml-language-server: $schema=PATH_TO_SCHEMA

# Reference a BSR-generated schema
yaml-language-server: $schema=https://buf.build/gen/archive/connectrpc/eliza/bufbuild/protoschema-jsonschema/raw/latest/connectrpc.eliza.v1.ConverseRequest.schema.json