Lexicon Overview

Understanding the AT Protocol Lexicon schema system

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

Resources

• Lexicon Specification
• XRPC Specification
• AT Protocol Documentation