Lexicon Overview - AT Protocol

What is Lexicon?

Lexicon is the schema system used by the AT Protocol to define the structure of data across the network. It provides a standardized way to describe records, queries, procedures, and subscriptions.

Core Concepts

Schema Types

Lexicon supports several types of schemas:

Records: Data structures stored in repositories (e.g., posts, profiles, follows)
Queries: Read-only operations that return data (e.g., get profile, get timeline)
Procedures: Write operations that modify state (e.g., create record, delete record)
Subscriptions: Real-time event streams (e.g., repository updates)

NSID Format

Every lexicon is identified by a Namespaced Identifier (NSID) using reverse domain notation:

com.atproto.repo.createRecord
app.bsky.feed.post

The format is: {authority}.{name}.{name}

Lexicon Namespaces

com.atproto.*

Core AT Protocol lexicons that provide fundamental functionality:

identity: DID and handle resolution
repo: Repository and record management
server: Account and session management
sync: Repository synchronization
admin: Administrative operations
moderation: Content reporting
label: Content labeling system

app.bsky.*

Bluesky application-specific lexicons:

actor: User profiles and preferences
feed: Posts, likes, reposts, and feeds
graph: Social graph (follows, blocks, lists)
notification: Notification system
labeler: Custom labeling services
embed: Rich embeds (images, videos, links)
richtext: Text formatting and facets

Data Types

Lexicon supports various data types:

Primitives

string: Text data
integer: Whole numbers
boolean: True/false values
unknown: Unstructured data

Formats

did: Decentralized Identifier
handle: User handle (e.g., alice.bsky.social)
at-uri: AT Protocol URI
at-identifier: Handle or DID
datetime: ISO 8601 timestamp
cid: Content Identifier
nsid: Namespaced Identifier
uri: Generic URI
language: BCP 47 language tag

Complex Types

object: Structured data with properties
array: List of items
union: One of several types
ref: Reference to another definition
blob: Binary data

Common Patterns

Pagination

Many queries support cursor-based pagination:

{
  limit: number,    // Maximum items to return (1-100)
  cursor?: string   // Pagination cursor from previous response
}

Response:

{
  cursor?: string,  // Next page cursor
  items: T[]        // Array of results
}

Authentication

Most write operations and some read operations require authentication via JWT:

Authorization: Bearer <accessJwt>

Error Handling

Lexicons define specific error types:

{
  error: string,        // Error code
  message?: string      // Human-readable message
}

Example Lexicon Structure

{
  "lexicon": 1,
  "id": "com.atproto.repo.createRecord",
  "defs": {
    "main": {
      "type": "procedure",
      "description": "Create a single new repository record.",
      "input": {
        "encoding": "application/json",
        "schema": {
          "type": "object",
          "required": ["repo", "collection", "record"],
          "properties": {
            "repo": {
              "type": "string",
              "format": "at-identifier"
            },
            "collection": {
              "type": "string",
              "format": "nsid"
            },
            "record": {
              "type": "unknown"
            }
          }
        }
      },
      "output": {
        "encoding": "application/json",
        "schema": {
          "type": "object",
          "required": ["uri", "cid"],
          "properties": {
            "uri": { "type": "string", "format": "at-uri" },
            "cid": { "type": "string", "format": "cid" }
          }
        }
      }
    }
  }
}

Using Lexicons

With TypeScript SDK

import { AtpAgent } from '@atproto/api'

const agent = new AtpAgent({ service: 'https://bsky.social' })

// Create a record using com.atproto.repo.createRecord
await agent.com.atproto.repo.createRecord({
  repo: agent.session.did,
  collection: 'app.bsky.feed.post',
  record: {
    $type: 'app.bsky.feed.post',
    text: 'Hello, AT Protocol!',
    createdAt: new Date().toISOString()
  }
})

Direct HTTP API

curl -X POST https://bsky.social/xrpc/com.atproto.repo.createRecord \
  -H "Authorization: Bearer $ACCESS_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "repo": "did:plc:...",
    "collection": "app.bsky.feed.post",
    "record": {
      "$type": "app.bsky.feed.post",
      "text": "Hello, AT Protocol!",
      "createdAt": "2024-03-04T12:00:00.000Z"
    }
  }'

Next Steps

Explore the specific lexicon namespaces:

com.atproto.identity - Identity resolution
com.atproto.repo - Repository management
com.atproto.server - Server operations
app.bsky.feed - Social feeds and posts
app.bsky.graph - Social graph

​What is Lexicon?

​Core Concepts

​Schema Types

​NSID Format

​Lexicon Namespaces

​com.atproto.*

​app.bsky.*

​Data Types

​Primitives

​Formats

​Complex Types

​Common Patterns

​Pagination

​Authentication

​Error Handling

​Example Lexicon Structure

​Using Lexicons

​With TypeScript SDK

​Direct HTTP API

​Next Steps

​Resources