resolve-lexicon

ATProto Lexicon network resolver. Resolves NSID (Namespaced Identifiers) to their corresponding Lexicon JSON schemas over the network.

Installation

npm install resolve-lexicon

Usage

import { resolveLexicon } from 'resolve-lexicon';

const json = await resolveLexicon('com.atproto.repo.getRecord');
console.log(json);

How it Works

The resolution process follows the Lexicon Publication and Distribution spec:

1. Parse NSID - Extract authority domain and name from the NSID

   • Example: com.atproto.repo.getRecord → authority: repo.atproto.com, name: getRecord

2. DNS Lookup - Query DNS TXT record for _lexicon.<authority>

   • Uses DNS-over-HTTPS (Cloudflare DNS API) for browser compatibility
   • Extracts DID from TXT record (format: did=did:plc:...)

3. DID Resolution - Resolve DID to PDS (Personal Data Server) endpoint

   • Supports did:plc via plc.directory
   • Supports did:web

4. Fetch Lexicon - Retrieve the lexicon record from PDS

   • Uses com.atproto.repo.getRecord XRPC endpoint
   • Collection: com.atproto.lexicon.schema
   • Record key: the NSID

API

resolveLexicon(nsid: string): Promise<LexiconDocument>

Resolves an NSID to its Lexicon schema.

Parameters:

• nsid - Namespaced identifier (e.g., "com.atproto.repo.getRecord")

Returns:

• Promise that resolves to a LexiconDocument

Types

interface LexiconDocument {
  lexicon: number
  id: string
  [key: string]: unknown
}

class LexiconResolverError extends Error {
  code: string
}

License

MIT