resolve-lexicon

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:

• Parse NSID - Extract authority domain and name from the NSID

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

• 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:...)

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

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

• 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