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>
:
<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:
<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:
<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.
Related docs
- Try the generated SDKs tutorial to learn how to generate SDKs from the BSR.