Buf Schema Registry / Generated SDKs

Maven/Gradle

The Buf Schema Registry provides generated SDKs for JVM-based languages in the form of a Maven repository, just like any other Java or Kotlin library. It generates SDKs automatically when you push schema changes, which eliminates the need to manage a Protobuf toolchain or generate code locally.

The BSR's Maven repository is hosted at https://buf.build/gen/maven. See the tutorial for instructions on how to access generated SDKs from the BSR directly.

Setup and usage

Follow the instructions for your package manager of choice below.

Setup

Update your pom.xml file to include the Buf Maven repository as a <repository>:

pom.xml

  <repositories>
    <repository>
      <name>Buf Maven Repository</name>
      <id>buf</id>
      <url>https://buf.build/gen/maven</url>
      <releases>
        <enabled>true</enabled>
      </releases>
      <snapshots>
        <enabled>false</enabled>
      </snapshots>
    </repository>
  </repositories>

The <id> value is important for using private generated SDKs because it must match the <id> in the <server> section of the ~/.m2/settings.xml file (see the private generated SDKs section for more details).

Adding a dependency

To add a dependency on a generated SDK, add the groupId, artifactId, and version to the <dependencies> section of your pom.xml file:

pom.xml

<dependencies>
  <dependency>
    <groupId>build.buf.gen</groupId>
    <artifactId>connectrpc_eliza_connectrpc_kotlin</artifactId>
    <version>0.3.0.2.20230913231627.233fca715f49</version>
  </dependency>
</dependencies>

See the names and versions section for syntax specifics.

Private generated SDKs

When using SDKs generated from private BSR repositories, you'll need to authenticate by including a personal API token for local use or a Bot user's API token for CI workflows. See the Authentication page for instructions.

To use private generated SDKs with Maven, edit your ~/.m2/settings.xml file to include your API token:

~/.m2/settings.xml

<settings>
  <servers>
    <!--
    Add this <server>, replacing {token} with your API Token.
    The <id> value must match the id of the Buf Maven repository in your
    pom.xml file - in this guide, it's `buf`.
    -->
    <server>
      <id>buf</id>
      <configuration>
        <httpHeaders>
          <property>
            <name>Authorization</name>
            <value>Bearer {token}</value>
          </property>
        </httpHeaders>
      </configuration>
    </server>
  </servers>
</settings>

Names and versions

The BSR Maven repository has a special syntax for SDK names:

{moduleOwner}_{moduleName}_{pluginOwner}_{pluginName}

For example, the SDK name connectrpc_eliza_connectrpc_kotlin contains code for the connectrpc/eliza module using the connectrpc/kotlin plugin.

Additionally, if a plugin supports the Java Protobuf Lite runtime, the name is suffixed with _lite:

{moduleOwner}_{moduleName}_{pluginOwner}_{pluginName}_lite

When installing the connectrpc_eliza_connectrpc_kotlin_lite SDK, the BSR generates code for the connectrpc/eliza module using the connectrpc/kotlin plugin, ensuring that dependencies are using the lite runtime, which makes the SDK suitable for use on Android.

Versions

To discover SDK versions for the Maven repository, you can browse a repository's SDK page, which has installation instructions and an interactive UI.

Full syntax

The version, revision, and commit information for plugins is appended to the SDK name described above with a preceding colon, with each field separated by .:

{sdkName}:{pluginVersion}.{pluginRevision}.{commitTimestamp}.{commitShortName}

As an example:

connectrpc_eliza_connectrpc_kotlin:0.3.0.2.20230913231627.233fca715f49

That represents:

Plugin version: 0.3.0
Plugin revision: 2
Commit timestamp: 20230913231627
Commit short name: 233fca715f49

For commits on branches, the commit timestamp component of the version is always zeroed out to easily differentiate SDK versions using commits on branches that are not main.

Available plugins

For a full list of supported plugins, navigate to the BSR plugins page and search for Java or Kotlin.

To learn more about how these plugins are packaged and distributed, go to the bufbuild/plugins repository. If you find a useful plugin that should be added, file an issue.

Try the generated SDKs tutorial to learn how to generate SDKs from the BSR.