at://

Publishing Lexicons

Sharing your lexicons with the world

Lexicon lifecycle

Lexicons are designed to be machine-readable and network-accessible. While it is not currently required that a Lexicon is available on the network, it is strongly advised to publish Lexicons so that a single canonical & authoritative representation is available to consumers of the method.

Lexicons are published to a PDS like any other AT record. They are resolved using DNS TXT records to link NSID namespaces to PDS repositories, so that when you address a Lexicon like com.atproto.example, atproto SDKs will know to look for an identity at atproto.com and retrieve the Lexicon from there.

For an NSID like app.toy.record:

  • The final segment record is the record/method name
  • The authority is app.toy; reversed, this becomes the domain toy.app
  • The DNS TXT record goes at _lexicon.toy.app

Each unique namespace prefix requires its own DNS TXT record, pointing to your DID. For example:

_lexicon.toy.app      TXT "did=did:plc:abc123..."
_lexicon.like.toy.app TXT "did=did:plc:abc123..."

Using goat

You can use goat, our command line tool, for creating and publishing Lexicons. The Lexicon-related features are available under goat lex :

  • publishing schemas to and synchronizing from the AT network
  • diffing, linting, and verifying schema evolution rules

goat can be installed from Homebrew on macOS and Linux:

brew install goat

In a project directory, you can download some existing Lexicons, which will get saved as JSON files in ./lexicons/:

$ goat lex pull com.atproto.repo.strongRef com.atproto.moderation. app.bsky.actor.profile
 🟢 com.atproto.repo.strongRef
 🟢 com.atproto.moderation.defs
 🟢 com.atproto.moderation.createReport
 🟢 app.bsky.actor.profile

You can also create a new Lexicon record with goat lex new record:

$ goat lex new record dev.project.thing

$ open ./lexicons/dev/project/thing.json

And eventually publish it with goat lex publish:

$ goat lex publish
 🟢 dev.project.thing

You'll need to log in with goat to publish to your PDS! To do this, use goat account login or set the GOAT_USERNAME and GOAT_PASSWORD environment variables.

Refer to the Lexicon Style Guide for guidance on creating new Lexicons.

Further Reading and Resources