CLAUDE.md#

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Overview#

This is slices-lexicon, a high-performance Rust library for AT Protocol lexicon validation. It validates AT Protocol lexicon documents and data records, with optional WebAssembly compilation for JavaScript/TypeScript environments.

Important: For the complete AT Protocol lexicon specification, refer to ../../context/lexicons_spec.md.

Development Commands#

Rust Library#

• cargo build - Build the library
• cargo test - Run tests
• cargo check - Analyze code without building
• cargo doc - Build documentation

WebAssembly Build#

• wasm-pack build --target web --features wasm - Build WASM module for web usage
• The WASM build outputs to pkg/ directory with JavaScript bindings

Testing#

• Run specific tests: cargo test test_name
• Run tests with output: cargo test -- --nocapture

Architecture#

This crate implements a modular, trait-based validation system for AT Protocol lexicons:

Core Components#

1. Validation Context (src/validation/context.rs)

   • Central state holder during validation
   • Manages loaded lexicon documents and reference resolution
   • Handles circular reference detection
   • Tracks validation paths for error reporting

2. Validator Trait (src/validation/traits.rs)

   • Common interface for all validators
   • Enables type-safe validation logic and easy testing

3. Validation Categories

   • Primary types (src/validation/primary/): record, query, procedure, subscription
   • Field types (src/validation/field/): object, array, union, ref
   • Primitive types (src/validation/primitive/): string, integer, boolean, bytes, blob, cid-link, null
   • Meta types (src/validation/meta/): token, unknown

Key Design Patterns#

• Builder Pattern: ValidationContextBuilder for configuring validation contexts
• Reference Resolution: Supports both local (#def) and global (lexicon#def) references
• Error Context: Detailed path tracking for pinpointing validation failures
• WASM Bindings: Optional WebAssembly exports when wasm feature is enabled

Entry Points#

• validate(lexicons) - Primary API for validating lexicon documents
• validate_record(lexicons, collection, record) - Validate data against a lexicon schema
• is_valid_nsid(nsid) - Utility for NSID format validation

WebAssembly Integration#

When compiled with --features wasm, the library exports:

• WasmLexiconValidator class for reusable validation
• validate_lexicons_and_get_errors() for one-off validation
• Individual format validation functions

String Formats Supported#

AT Protocol string formats: datetime, uri, at-uri, did, handle, at-identifier, nsid, cid, language, tid, record-key

Error Handling#

Uses thiserror for structured error types. Validation errors include detailed context about location and cause, making debugging straightforward.

Project Structure#

src/
├── lib.rs                    # Main library entry point with public APIs
├── types.rs                  # Core types (LexiconDoc, StringFormat)
├── errors.rs                 # Error definitions using thiserror
└── validation/
    ├── mod.rs               # Validation module exports
    ├── context.rs           # ValidationContext and builder
    ├── traits.rs            # Validator trait definition
    ├── constraints.rs       # Common validation constraints
    ├── resolution.rs        # Reference resolution utilities
    ├── primary/             # Primary AT Protocol types
    │   ├── mod.rs
    │   ├── record.rs        # Record type validator
    │   ├── query.rs         # Query endpoint validator
    │   ├── procedure.rs     # Procedure endpoint validator
    │   └── subscription.rs  # Subscription validator
    ├── field/               # Field/container types
    │   ├── mod.rs
    │   ├── object.rs        # Object validator with properties
    │   ├── array.rs         # Array validator with constraints
    │   ├── union.rs         # Union type validator
    │   └── reference.rs     # Reference validator (resolves $ref)
    ├── primitive/           # Primitive data types
    │   ├── mod.rs
    │   ├── string.rs        # String validation with format checking
    │   ├── integer.rs       # Integer with min/max constraints
    │   ├── boolean.rs       # Boolean validation
    │   ├── bytes.rs         # Base64 bytes validation
    │   ├── blob.rs          # Blob (binary data) validation
    │   ├── cid_link.rs      # CID link validation
    │   └── null.rs          # Null value validation
    └── meta/                # Meta types for schema composition
        ├── mod.rs
        ├── token.rs         # Token (unit type) validator
        └── unknown.rs       # Unknown type validator

Key Files#

• lib.rs - Contains main APIs, WASM bindings, and comprehensive examples
• validation/context.rs - Core validation state management and reference resolution
• validation/primitive/string.rs - Extensive AT Protocol string format validation
• pkg/ - Generated WASM artifacts (created by wasm-pack build)