Backfill in-progress. Some lexicons and records may be missing or incomplete.

Adding Lexicons to Lexicon Garden

This guide walks you through the process of creating, validating, and publishing lexicon schemas.

Overview

  1. Schemas are stored in your PDS under the com.atproto.lexicon.schema collection, with the NSID as the rkey.
  2. A DNS entry is used to resolve lexicon NSIDs to the repository containing the lexicon schema definitions.

Prerequisites

  • An ATProtocol PDS (Bluesky account or self-hosted)
  • Your lexicon schema JSON files
  • DNS control for your domain (for authority verification)
  • The goat CLI tool (recommended)

Step 1: Define Your Lexicon

Create your lexicon schema following the NSID naming convention (reverse domain notation):

  • com.example.myapp.record for records
  • com.example.myapp.defs for shared definitions

See the ATProtocol Lexicon Specification for schema structure details.

Step 2: Validate Your Lexicon

Use goat to validate your lexicon schema:

goat lex validate ./lexicons/com.example.myapp.record.json

This ensures the schema definition is valid and adheres to the ATProtocol lexicon spec. Fix any validation errors before proceeding.

Step 3: Lint Your Lexicon

Use goat to lint your lexicon for best practices:

goat lex lint ./lexicons/com.example.myapp.record.json

Address any warnings or suggestions to ensure your lexicon follows best practices.

Step 4: Set Up DNS for Authority

Lexicon resolution uses DNS TXT records to link NSID namespaces to repositories. The authority domain is derived by removing the final NSID segment (the method/record name) and reversing the remaining parts[1].

Understanding NSID Authority

For an NSID like com.example.feed.post:

  • The final segment post is the record/method name
  • The authority is com.example.feed
  • Reversed, this becomes the domain feed.example.com
  • The DNS TXT record goes at _lexicon.feed.example.com

Each Namespace Depth Needs Its Own DNS Entry

Resolvers do not recurse up or down the DNS hierarchy[1]. If a DNS lookup fails, resolution fails entirely. This means each unique namespace prefix requires its own DNS entry:

NSID Authority DNS Entry
com.example.post com.example _lexicon.example.com
com.example.feed.post com.example.feed _lexicon.feed.example.com
com.example.feed.like com.example.feed _lexicon.feed.example.com
com.example.graph.follow com.example.graph _lexicon.graph.example.com

Notice that com.example.feed.post and com.example.feed.like share the same authority (they differ only in the final segment), so they use the same DNS entry and are stored in the same repository with different rkeys.

Creating DNS Entries

For each unique namespace depth, add a _lexicon TXT record pointing to your DID:

_lexicon.example.com      TXT "did=did:plc:abc123..."
_lexicon.feed.example.com TXT "did=did:plc:abc123..."

The did= prefix is required. Lexicon Garden displays an authority badge for schemas published by the verified domain authority.

Step 5: Publish Your Schema

Use goat to publish your lexicons:

goat lex publish ./lexicons

Publishing with goat includes:

  • Checking the necessary DNS entries for lexicon resolution
  • Validating the lexicon schema
  • Creating the record in your repository

Step 6: Verify on Lexicon Garden

  1. Search for your NSID on Lexicon Garden
  2. Check that the authority badge appears
  3. View the Documentation and Graph tabs to ensure everything looks correct

Caching and Propagation

Lexicon Garden caches identity and authority data. It can take up to 24 hours for changes to be fully reflected. If your lexicon or authority badge doesn't appear immediately:

  • DNS propagation: Lexicon Garden uses Google (8.8.8.8) and Cloudflare (1.1.1.1) nameservers for resolving identities and lexicon authorities. New DNS records may take time to propagate to these resolvers.
  • Identity caching: DID resolution results are cached for 12 hours.
  • Schema indexing: New schemas are indexed as they appear on TAP, which depends on your PDS syncing with the relay.
  1. ATProtocol Lexicon Specification - Publication and Resolution ↩

Lexicon Garden

@