Skip to main content

​
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:

​
Resources

Build docs developers (and LLMs) love

Get started for freeTalk to us