lexicon schema derive macro

Cargo.lock

···
 name = "jacquard-derive"
 version = "0.8.0"
 dependencies = [
+ "heck 0.5.0",
+ "inventory",
  "jacquard-common 0.8.0",
  "jacquard-lexicon 0.8.0",
  "proc-macro2",
···
  "serde",
  "serde_json",
  "syn 2.0.108",
+ "unicode-segmentation",
 ]
 
 [[package]]
···
 dependencies = [
  "glob",
  "heck 0.5.0",
+ "inventory",
  "jacquard-common 0.8.0",
  "miette",
  "prettyplease",
···
  "syn 2.0.108",
  "tempfile",
  "thiserror 2.0.17",
+ "unicode-segmentation",
  "walkdir",
 ]
 
···
 version = "0.1.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "3b09c83c3c29d37506a3e260c08c03743a6bb66a9cd432c6934ab501a190571f"
+
+[[package]]
+name = "unicode-segmentation"
+version = "1.12.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f6ccf251212114b54433ec949fd6a7841275f9ada20dddd2f29e9ceea4501493"
 
 [[package]]
 name = "unicode-width"

crates/jacquard-axum/tests/extractor_tests.rs

···
 async fn test_handler(ExtractXrpc(req): ExtractXrpc<TestQueryRequest<'_>>) -> impl IntoResponse {
     Json(TestQueryResponse {
         did: req.did,
-        extra_data: None,
+        extra_data: BTreeMap::new(),
     })
 }
 

crates/jacquard-axum/tests/service_auth_tests.rs

···
             r#type: CowStr::new_static("Multikey"),
             controller: Some(CowStr::Owned(did.into())),
             public_key_multibase: Some(CowStr::Owned(multibase_key.into())),
-            extra_data: None,
+            extra_data: BTreeMap::new(),
         }]),
         service: None,
-        extra_data: None,
+        extra_data: BTreeMap::new(),
     }
 }
 

crates/jacquard-derive/Cargo.toml

···
 proc-macro = true
 
 [dependencies]
+heck.workspace = true
 jacquard-lexicon = { version = "0.8", path = "../jacquard-lexicon" }
 proc-macro2.workspace = true
 quote.workspace = true
 syn.workspace = true
 
 [dev-dependencies]
+inventory = "0.3"
 jacquard-common = { version = "0.8", path = "../jacquard-common" }
+jacquard-lexicon = { version = "0.8", path = "../jacquard-lexicon" }
 serde.workspace = true
 serde_json.workspace = true
+unicode-segmentation = "1.12"

crates/jacquard-derive/src/lib.rs

···
 //!
 //! This crate provides attribute and derive macros for working with Jacquard types.
 //! The code generator uses `#[lexicon]` and `#[open_union]` to add lexicon-specific behavior.
-//! You'll use `#[derive(IntoStatic)]` frequently, and `#[derive(XrpcRequest)]` when defining
-//! custom XRPC endpoints.
+//! You'll use `#[derive(IntoStatic)]` frequently, `#[derive(XrpcRequest)]` when defining
+//! custom XRPC endpoints, and `#[derive(LexiconSchema)]` for reverse codegen (Rust → lexicon).
 //!
 //! ## Macros
 //!
···
 //! // - impl XrpcResp for GetThingResponse
 //! // - impl XrpcRequest for GetThing
 //! ```
+//!
+//! ### `#[derive(LexiconSchema)]`
+//!
+//! Derives `LexiconSchema` trait for reverse codegen (Rust → lexicon JSON). Generate
+//! lexicon schemas from your Rust types for rapid prototyping and custom lexicons.
+//!
+//! **Type-level attributes** (`#[lexicon(...)]`):
+//! - `nsid = "..."`: The lexicon NSID (required)
+//! - `record`: Mark as a record type (requires `key`)
+//! - `object`: Mark as an object type (default if neither record/procedure/query)
+//! - `key = "..."`: Record key type (`"tid"`, `"literal:self"`, or custom)
+//! - `fragment = "..."`: Fragment name for non-main defs
+//!
+//! **Field-level attributes** (`#[lexicon(...)]`):
+//! - `max_length = N`: Max byte length for strings
+//! - `max_graphemes = N`: Max grapheme count for strings
+//! - `min_length = N`, `min_graphemes = N`: Minimum constraints
+//! - `minimum = N`, `maximum = N`: Integer range constraints
+//!
+//! **Serde integration**: Respects `#[serde(rename)]`, `#[serde(rename_all)]`, and
+//! `#[serde(skip)]`. Defaults to camelCase for field names (lexicon standard).
+//!
+//! **Enums**: Closed unions by default. Add `#[open_union]` for open unions. Variant
+//! refs resolved via `#[nsid = "..."]` > `#[serde(rename = "...")]` > fragment inference.
+//!
+//! ```ignore
+//! // Record with constraints
+//! #[derive(LexiconSchema)]
+//! #[lexicon(nsid = "app.bsky.feed.post", record, key = "tid")]
+//! struct Post<'a> {
+//!     #[lexicon(max_graphemes = 300, max_length = 3000)]
+//!     pub text: CowStr<'a>,
+//!     pub created_at: Datetime,  // -> "createdAt" (camelCase)
+//! }
+//!
+//! // Closed union
+//! #[derive(LexiconSchema)]
+//! #[lexicon(nsid = "app.bsky.feed.defs")]
+//! enum FeedViewPref {
+//!     #[nsid = "app.bsky.feed.defs#feedViewPref"]
+//!     Feed,
+//!     #[nsid = "app.bsky.feed.defs#threadViewPref"]
+//!     Thread,
+//! }
+//! ```
 
 use proc_macro::TokenStream;
 
···
 pub fn derive_xrpc_request(input: TokenStream) -> TokenStream {
     jacquard_lexicon::derive_impl::impl_derive_xrpc_request(input.into()).into()
 }
+
+/// Derive macro for `LexiconSchema` trait.
+///
+/// Generates `LexiconSchema` trait impl from Rust types for reverse codegen (Rust → lexicon JSON).
+/// Produces lexicon schema definitions and runtime validation code from your type definitions.
+///
+/// **What it generates:**
+/// - `impl LexiconSchema` with `nsid()`, `schema_id()`, and `lexicon_doc()` methods
+/// - `validate()` method that checks constraints at runtime
+/// - `inventory::submit!` registration for schema discovery (Phase 3)
+///
+/// **Attributes:** `#[lexicon(...)]` and `#[nsid = "..."]` on types and fields.
+/// See crate docs for full attribute reference and examples.
+#[proc_macro_derive(LexiconSchema, attributes(lexicon, nsid))]
+pub fn derive_lexicon_schema(input: TokenStream) -> TokenStream {
+    jacquard_lexicon::derive_impl::impl_derive_lexicon_schema(input.into()).into()
+}

crates/jacquard-derive/tests/lexicon_schema_derive.rs

···
+use jacquard_common::CowStr;
+use jacquard_common::types::string::Datetime;
+use jacquard_derive::{LexiconSchema, open_union};
+use jacquard_lexicon::schema::{LexiconGenerator, LexiconSchema as LexiconSchemaTrait};
+use serde::{Deserialize, Serialize};
+
+#[test]
+fn test_simple_struct() {
+    #[derive(LexiconSchema)]
+    #[lexicon(nsid = "com.example.simple", record, key = "tid")]
+    struct SimpleRecord<'a> {
+        pub text: CowStr<'a>,
+        pub created_at: Datetime,
+    }
+
+    assert_eq!(SimpleRecord::nsid(), "com.example.simple");
+    assert_eq!(SimpleRecord::schema_id().as_ref(), "com.example.simple");
+
+    let mut generator = LexiconGenerator::new(SimpleRecord::nsid());
+    let doc = SimpleRecord::lexicon_doc(&mut generator);
+
+    assert_eq!(doc.id.as_ref(), "com.example.simple");
+    assert!(doc.defs.contains_key("main"));
+
+    // Serialize to JSON to verify structure
+    let json = serde_json::to_string_pretty(&doc).unwrap();
+    println!("{}", json);
+
+    // Should contain record type
+    assert!(json.contains("\"type\": \"record\""));
+    // Should have camelCase field names (default)
+    assert!(json.contains("\"createdAt\""));
+}
+
+#[test]
+fn test_struct_with_constraints() {
+    #[derive(LexiconSchema)]
+    #[lexicon(nsid = "com.example.constrained", record)]
+    struct ConstrainedRecord<'a> {
+        #[lexicon(max_graphemes = 300, max_length = 3000)]
+        pub text: CowStr<'a>,
+
+        #[lexicon(minimum = 0, maximum = 100)]
+        pub score: i64,
+    }
+
+    let mut generator = LexiconGenerator::new(ConstrainedRecord::nsid());
+    let doc = ConstrainedRecord::lexicon_doc(&mut generator);
+
+    let json = serde_json::to_string_pretty(&doc).unwrap();
+    println!("{}", json);
+
+    // Verify constraints are in schema
+    assert!(json.contains("\"maxGraphemes\": 300"));
+    assert!(json.contains("\"maxLength\": 3000"));
+    assert!(json.contains("\"minimum\": 0"));
+    assert!(json.contains("\"maximum\": 100"));
+}
+
+#[test]
+fn test_validation() {
+    #[derive(LexiconSchema)]
+    #[lexicon(nsid = "com.example.validated", record)]
+    struct ValidatedRecord<'a> {
+        #[lexicon(max_length = 100)]
+        pub text: CowStr<'a>,
+
+        #[lexicon(minimum = 0, maximum = 10)]
+        pub count: i64,
+    }
+
+    // Valid
+    let valid = ValidatedRecord {
+        text: "hello".into(),
+        count: 5,
+    };
+    assert!(valid.validate().is_ok());
+
+    // Text too long
+    let invalid_text = ValidatedRecord {
+        text: "a".repeat(150).into(),
+        count: 5,
+    };
+    assert!(invalid_text.validate().is_err());
+
+    // Count too high
+    let invalid_count = ValidatedRecord {
+        text: "hello".into(),
+        count: 15,
+    };
+    assert!(invalid_count.validate().is_err());
+
+    // Count too low
+    let invalid_low = ValidatedRecord {
+        text: "hello".into(),
+        count: -5,
+    };
+    assert!(invalid_low.validate().is_err());
+}
+
+#[test]
+fn test_serde_rename() {
+    #[derive(Serialize, Deserialize, LexiconSchema)]
+    #[lexicon(nsid = "com.example.renamed", record)]
+    #[serde(rename_all = "snake_case")]
+    struct RenamedRecord {
+        pub some_field: i64,
+        pub another_field: i64,
+    }
+
+    let mut generator = LexiconGenerator::new(RenamedRecord::nsid());
+    let doc = RenamedRecord::lexicon_doc(&mut generator);
+
+    let json = serde_json::to_string_pretty(&doc).unwrap();
+    println!("{}", json);
+
+    // Should use snake_case not camelCase
+    assert!(json.contains("\"some_field\""));
+    assert!(json.contains("\"another_field\""));
+}
+
+#[test]
+fn test_default_camel_case() {
+    #[derive(LexiconSchema)]
+    #[lexicon(nsid = "com.example.camel", record)]
+    struct CamelCaseRecord {
+        pub field_one: i64,
+        pub field_two: i64,
+    }
+
+    let mut generator = LexiconGenerator::new(CamelCaseRecord::nsid());
+    let doc = CamelCaseRecord::lexicon_doc(&mut generator);
+
+    let json = serde_json::to_string_pretty(&doc).unwrap();
+    println!("{}", json);
+
+    // Should default to camelCase
+    assert!(json.contains("\"fieldOne\""));
+    assert!(json.contains("\"fieldTwo\""));
+}
+
+#[test]
+fn test_basic_enum() {
+    #[derive(LexiconSchema)]
+    #[lexicon(nsid = "com.example.union")]
+    enum BasicUnion {
+        #[nsid = "com.example.variant.one"]
+        VariantOne,
+
+        #[nsid = "com.example.variant.two"]
+        VariantTwo,
+    }
+
+    let mut generator = LexiconGenerator::new(BasicUnion::nsid());
+    let doc = BasicUnion::lexicon_doc(&mut generator);
+
+    let json = serde_json::to_string_pretty(&doc).unwrap();
+    println!("{}", json);
+
+    // Should be a union type
+    assert!(json.contains("\"type\": \"union\""));
+    // Should have refs
+    assert!(json.contains("com.example.variant.one"));
+    assert!(json.contains("com.example.variant.two"));
+    // Should be closed by default
+    assert!(json.contains("\"closed\": true"));
+}
+
+#[test]
+fn test_open_union() {
+    #[derive(LexiconSchema)]
+    #[lexicon(nsid = "com.example.open")]
+    #[open_union]
+    enum OpenUnion<'a> {
+        #[nsid = "com.example.variant"]
+        Variant,
+
+        Unknown(jacquard_common::types::value::Data<'a>),
+    }
+
+    let mut generator = LexiconGenerator::new(OpenUnion::nsid());
+    let doc = OpenUnion::lexicon_doc(&mut generator);
+
+    let json = serde_json::to_string_pretty(&doc).unwrap();
+    println!("{}", json);
+
+    // Should be open (closed field omitted, defaults to open)
+    assert!(!json.contains("\"closed\""));
+}
+
+#[test]
+fn test_enum_with_serde_rename() {
+    #[derive(Serialize, Deserialize, LexiconSchema)]
+    #[lexicon(nsid = "com.example.renamed_union")]
+    enum RenamedUnion {
+        #[serde(rename = "app.bsky.embed.images")]
+        Images,
+
+        #[serde(rename = "app.bsky.embed.video")]
+        Video,
+    }
+
+    let mut generator = LexiconGenerator::new(RenamedUnion::nsid());
+    let doc = RenamedUnion::lexicon_doc(&mut generator);
+
+    let json = serde_json::to_string_pretty(&doc).unwrap();
+    println!("{}", json);
+
+    // Should use serde rename values
+    assert!(json.contains("app.bsky.embed.images"));
+    assert!(json.contains("app.bsky.embed.video"));
+}
+
+#[test]
+fn test_enum_fragment_inference() {
+    #[derive(LexiconSchema)]
+    #[lexicon(nsid = "com.example.fragments")]
+    enum FragmentUnion {
+        // Should generate com.example.fragments#variantOne
+        VariantOne,
+        // Should generate com.example.fragments#variantTwo
+        VariantTwo,
+    }
+
+    let mut generator = LexiconGenerator::new(FragmentUnion::nsid());
+    let doc = FragmentUnion::lexicon_doc(&mut generator);
+
+    let json = serde_json::to_string_pretty(&doc).unwrap();
+    println!("{}", json);
+
+    // Should have fragment refs
+    assert!(json.contains("com.example.fragments#variantOne"));
+    assert!(json.contains("com.example.fragments#variantTwo"));
+}

crates/jacquard-identity/src/resolver.rs

···
                         service_endpoint: Some(Data::String(AtprotoStr::Uri(Uri::Https(
                             Url::from_str(&mini_doc.pds).unwrap(),
                         )))),
-                        extra_data: None,
+                        extra_data: BTreeMap::new(),
                     }]),
-                    extra_data: None,
+                    extra_data: BTreeMap::new(),
                 })
             } else {
                 Err(IdentityError::missing_pds_endpoint())
···
                         service_endpoint: Some(Data::String(AtprotoStr::Uri(Uri::Https(
                             Url::from_str(&mini_doc.pds).unwrap(),
                         )))),
-                        extra_data: None,
+                        extra_data: BTreeMap::new(),
                     }]),
-                    extra_data: None,
+                    extra_data: BTreeMap::new(),
                 }
                 .into_static())
             } else {

crates/jacquard-lexicon/Cargo.toml

···
 [dependencies]
 glob = "0.3"
 heck.workspace = true
+inventory = "0.3"
 jacquard-common = { version = "0.8", path = "../jacquard-common" }
 miette = { workspace = true, features = ["fancy"] }
 prettyplease.workspace = true
···
 serde_with.workspace = true
 syn.workspace = true
 thiserror.workspace = true
+unicode-segmentation = "1.12"
 walkdir = "2.5"
 
 [dev-dependencies]

crates/jacquard-lexicon/src/codegen.rs

···
                 self.subscription_files.borrow_mut().insert(file_path);
                 self.generate_subscription(nsid, def_name, sub)
             }
+            LexUserType::Union(union) => {
+                // Top-level union generates an enum
+                let type_name = self.def_to_type_name(nsid, def_name);
+                let refs: Vec<_> = union.refs.iter().cloned().collect();
+                self.generate_union(nsid, &type_name, &refs, union.description.as_ref().map(|d| d.as_ref()), union.closed)
+            }
         }
     }
 }

crates/jacquard-lexicon/src/codegen/lifetime.rs

···
 use super::CodeGenerator;
-use crate::lexicon::{
-    LexArrayItem, LexObjectProperty, LexString, LexStringFormat, LexUserType,
-};
+use crate::lexicon::{LexArrayItem, LexObjectProperty, LexString, LexStringFormat, LexUserType};
 
 impl<'c> CodeGenerator<'c> {
     /// Check if a property type needs a lifetime parameter
···
     /// Check if a lexicon def needs a lifetime parameter
     pub(super) fn def_needs_lifetime(&self, def: &LexUserType<'static>) -> bool {
         match def {
-            // Records and Objects always have lifetimes now since they get #[lexicon] attribute
             LexUserType::Record(_) => true,
             LexUserType::Object(_) => true,
             LexUserType::Token(_) => false,
···
                 // Shouldn't be referenced directly
                 true
             }
+            LexUserType::Union(_) => false, // Unions are just refs, no lifetime needed
         }
     }
 
     /// Check if xrpc params need a lifetime parameter
-    pub(super) fn params_need_lifetime(&self, params: &crate::lexicon::LexXrpcParameters<'static>) -> bool {
+    pub(super) fn params_need_lifetime(
+        &self,
+        params: &crate::lexicon::LexXrpcParameters<'static>,
+    ) -> bool {
         params.properties.values().any(|prop| {
             use crate::lexicon::LexXrpcParametersProperty;
             match prop {

crates/jacquard-lexicon/src/derive_impl/lexicon_schema.rs

···
+//! Implementation of #[derive(LexiconSchema)] macro
+
+use crate::lexicon::{
+    LexArray, LexBlob, LexBoolean, LexBytes, LexCidLink, LexInteger, LexObject, LexObjectProperty,
+    LexRef, LexRefUnion, LexString, LexStringFormat, LexUnknown, LexUserType,
+};
+use crate::schema::type_mapping::{LexiconPrimitiveType, StringFormat, rust_type_to_lexicon_type};
+use heck::{ToKebabCase, ToLowerCamelCase, ToPascalCase, ToShoutySnakeCase, ToSnakeCase};
+use jacquard_common::smol_str::{SmolStr, ToSmolStr};
+use proc_macro2::TokenStream;
+use quote::{ToTokens, quote};
+use syn::{Attribute, Data, DeriveInput, Fields, Ident, LitStr, Type, parse2};
+
+/// Implementation for the LexiconSchema derive macro
+pub fn impl_derive_lexicon_schema(input: TokenStream) -> TokenStream {
+    let input = match parse2::<DeriveInput>(input) {
+        Ok(input) => input,
+        Err(e) => return e.to_compile_error(),
+    };
+
+    match lexicon_schema_impl(&input) {
+        Ok(tokens) => tokens,
+        Err(e) => e.to_compile_error(),
+    }
+}
+
+fn lexicon_schema_impl(input: &DeriveInput) -> syn::Result<TokenStream> {
+    // Parse type-level attributes
+    let type_attrs = parse_type_attrs(&input.attrs)?;
+
+    // Determine NSID
+    let nsid = determine_nsid(&type_attrs, input)?;
+
+    // Generate based on data type
+    match &input.data {
+        Data::Struct(data_struct) => impl_for_struct(input, &type_attrs, &nsid, data_struct),
+        Data::Enum(data_enum) => impl_for_enum(input, &type_attrs, &nsid, data_enum),
+        Data::Union(_) => Err(syn::Error::new_spanned(
+            input,
+            "LexiconSchema cannot be derived for unions",
+        )),
+    }
+}
+
+/// Parsed lexicon attributes from type
+#[derive(Debug, Default)]
+struct LexiconTypeAttrs {
+    /// NSID for this type (required for primary types)
+    nsid: Option<String>,
+
+    /// Fragment name (None = not a fragment, Some("") = infer from type name)
+    fragment: Option<String>,
+
+    /// Type kind
+    kind: Option<LexiconTypeKind>,
+
+    /// Record key type (for records)
+    key: Option<String>,
+}
+
+#[derive(Debug, Clone, Copy)]
+enum LexiconTypeKind {
+    Record,
+    Query,
+    Procedure,
+    Subscription,
+    Object,
+    Union,
+}
+
+/// Parse type-level lexicon attributes
+fn parse_type_attrs(attrs: &[Attribute]) -> syn::Result<LexiconTypeAttrs> {
+    let mut result = LexiconTypeAttrs::default();
+
+    for attr in attrs {
+        if !attr.path().is_ident("lexicon") {
+            continue;
+        }
+
+        attr.parse_nested_meta(|meta| {
+            if meta.path.is_ident("nsid") {
+                let value = meta.value()?;
+                let lit: LitStr = value.parse()?;
+                result.nsid = Some(lit.value());
+                Ok(())
+            } else if meta.path.is_ident("fragment") {
+                // Two forms: #[lexicon(fragment)] or #[lexicon(fragment = "name")]
+                if meta.input.peek(syn::Token![=]) {
+                    let value = meta.value()?;
+                    let lit: LitStr = value.parse()?;
+                    result.fragment = Some(lit.value());
+                } else {
+                    result.fragment = Some(String::new()); // Infer from type name
+                }
+                Ok(())
+            } else if meta.path.is_ident("record") {
+                result.kind = Some(LexiconTypeKind::Record);
+                Ok(())
+            } else if meta.path.is_ident("query") {
+                result.kind = Some(LexiconTypeKind::Query);
+                Ok(())
+            } else if meta.path.is_ident("procedure") {
+                result.kind = Some(LexiconTypeKind::Procedure);
+                Ok(())
+            } else if meta.path.is_ident("subscription") {
+                result.kind = Some(LexiconTypeKind::Subscription);
+                Ok(())
+            } else if meta.path.is_ident("key") {
+                let value = meta.value()?;
+                let lit: LitStr = value.parse()?;
+                result.key = Some(lit.value());
+                Ok(())
+            } else {
+                Err(meta.error("unknown lexicon attribute"))
+            }
+        })?;
+    }
+
+    Ok(result)
+}
+
+/// Parsed lexicon attributes from field
+#[derive(Debug, Default)]
+struct LexiconFieldAttrs {
+    max_length: Option<usize>,
+    max_graphemes: Option<usize>,
+    min_length: Option<usize>,
+    min_graphemes: Option<usize>,
+    minimum: Option<i64>,
+    maximum: Option<i64>,
+    explicit_ref: Option<String>,
+    format: Option<String>,
+}
+
+/// Parse field-level lexicon attributes
+fn parse_field_attrs(attrs: &[Attribute]) -> syn::Result<LexiconFieldAttrs> {
+    let mut result = LexiconFieldAttrs::default();
+
+    for attr in attrs {
+        if !attr.path().is_ident("lexicon") {
+            continue;
+        }
+
+        attr.parse_nested_meta(|meta| {
+            if meta.path.is_ident("max_length") {
+                let value = meta.value()?;
+                let lit: syn::LitInt = value.parse()?;
+                result.max_length = Some(lit.base10_parse()?);
+                Ok(())
+            } else if meta.path.is_ident("max_graphemes") {
+                let value = meta.value()?;
+                let lit: syn::LitInt = value.parse()?;
+                result.max_graphemes = Some(lit.base10_parse()?);
+                Ok(())
+            } else if meta.path.is_ident("min_length") {
+                let value = meta.value()?;
+                let lit: syn::LitInt = value.parse()?;
+                result.min_length = Some(lit.base10_parse()?);
+                Ok(())
+            } else if meta.path.is_ident("min_graphemes") {
+                let value = meta.value()?;
+                let lit: syn::LitInt = value.parse()?;
+                result.min_graphemes = Some(lit.base10_parse()?);
+                Ok(())
+            } else if meta.path.is_ident("minimum") {
+                let value = meta.value()?;
+                let lit: syn::LitInt = value.parse()?;
+                result.minimum = Some(lit.base10_parse()?);
+                Ok(())
+            } else if meta.path.is_ident("maximum") {
+                let value = meta.value()?;
+                let lit: syn::LitInt = value.parse()?;
+                result.maximum = Some(lit.base10_parse()?);
+                Ok(())
+            } else if meta.path.is_ident("ref") {
+                let value = meta.value()?;
+                let lit: LitStr = value.parse()?;
+                result.explicit_ref = Some(lit.value());
+                Ok(())
+            } else if meta.path.is_ident("format") {
+                let value = meta.value()?;
+                let lit: LitStr = value.parse()?;
+                result.format = Some(lit.value());
+                Ok(())
+            } else {
+                Err(meta.error("unknown lexicon field attribute"))
+            }
+        })?;
+    }
+
+    Ok(result)
+}
+
+/// Parsed serde attributes relevant to lexicon schema
+#[derive(Debug, Default)]
+struct SerdeAttrs {
+    rename: Option<String>,
+    skip: bool,
+}
+
+/// Parse serde attributes for a field
+fn parse_serde_attrs(attrs: &[Attribute]) -> syn::Result<SerdeAttrs> {
+    let mut result = SerdeAttrs::default();
+
+    for attr in attrs {
+        if !attr.path().is_ident("serde") {
+            continue;
+        }
+
+        attr.parse_nested_meta(|meta| {
+            if meta.path.is_ident("rename") {
+                let value = meta.value()?;
+                let lit: LitStr = value.parse()?;
+                result.rename = Some(lit.value());
+                Ok(())
+            } else if meta.path.is_ident("skip") {
+                result.skip = true;
+                Ok(())
+            } else {
+                // Ignore other serde attributes
+                Ok(())
+            }
+        })?;
+    }
+
+    Ok(result)
+}
+
+/// Parse container-level serde rename_all
+fn parse_serde_rename_all(attrs: &[Attribute]) -> syn::Result<Option<RenameRule>> {
+    for attr in attrs {
+        if !attr.path().is_ident("serde") {
+            continue;
+        }
+
+        let mut found_rule = None;
+        attr.parse_nested_meta(|meta| {
+            if meta.path.is_ident("rename_all") {
+                let value = meta.value()?;
+                let lit: LitStr = value.parse()?;
+                found_rule = RenameRule::from_str(&lit.value());
+                Ok(())
+            } else {
+                Ok(())
+            }
+        })?;
+
+        if found_rule.is_some() {
+            return Ok(found_rule);
+        }
+    }
+
+    // Default to camelCase (lexicon standard)
+    Ok(Some(RenameRule::CamelCase))
+}
+
+#[derive(Debug, Clone, Copy)]
+enum RenameRule {
+    CamelCase,
+    SnakeCase,
+    PascalCase,
+    ScreamingSnakeCase,
+    KebabCase,
+}
+
+impl RenameRule {
+    fn from_str(s: &str) -> Option<Self> {
+        match s {
+            "camelCase" => Some(RenameRule::CamelCase),
+            "snake_case" => Some(RenameRule::SnakeCase),
+            "PascalCase" => Some(RenameRule::PascalCase),
+            "SCREAMING_SNAKE_CASE" => Some(RenameRule::ScreamingSnakeCase),
+            "kebab-case" => Some(RenameRule::KebabCase),
+            _ => None,
+        }
+    }
+
+    fn apply(&self, input: &str) -> String {
+        match self {
+            RenameRule::CamelCase => input.to_lower_camel_case(),
+            RenameRule::SnakeCase => input.to_snake_case(),
+            RenameRule::PascalCase => input.to_pascal_case(),
+            RenameRule::ScreamingSnakeCase => input.to_shouty_snake_case(),
+            RenameRule::KebabCase => input.to_kebab_case(),
+        }
+    }
+}
+
+/// Determine NSID from attributes and context
+fn determine_nsid(attrs: &LexiconTypeAttrs, input: &DeriveInput) -> syn::Result<String> {
+    // Explicit NSID in lexicon attribute
+    if let Some(nsid) = &attrs.nsid {
+        return Ok(nsid.clone());
+    }
+
+    // Fragment - need to find module NSID (not implemented yet)
+    if attrs.fragment.is_some() {
+        return Err(syn::Error::new_spanned(
+            input,
+            "fragments require explicit nsid or module-level primary type (not yet implemented)",
+        ));
+    }
+
+    // Check for XrpcRequest derive with NSID
+    if let Some(nsid) = extract_xrpc_nsid(&input.attrs)? {
+        return Ok(nsid);
+    }
+
+    Err(syn::Error::new_spanned(
+        input,
+        "missing required `nsid` attribute (use #[lexicon(nsid = \"...\")] or #[xrpc(nsid = \"...\")])",
+    ))
+}
+
+/// Extract NSID from XrpcRequest attributes (cross-derive coordination)
+fn extract_xrpc_nsid(attrs: &[Attribute]) -> syn::Result<Option<String>> {
+    for attr in attrs {
+        if !attr.path().is_ident("xrpc") {
+            continue;
+        }
+
+        let mut nsid = None;
+        attr.parse_nested_meta(|meta| {
+            if meta.path.is_ident("nsid") {
+                let value = meta.value()?;
+                let lit: LitStr = value.parse()?;
+                nsid = Some(lit.value());
+            }
+            Ok(())
+        })?;
+
+        if let Some(nsid) = nsid {
+            return Ok(Some(nsid));
+        }
+    }
+    Ok(None)
+}
+
+/// Struct implementation
+fn impl_for_struct(
+    input: &DeriveInput,
+    type_attrs: &LexiconTypeAttrs,
+    nsid: &str,
+    data_struct: &syn::DataStruct,
+) -> syn::Result<TokenStream> {
+    let name = &input.ident;
+    let generics = &input.generics;
+
+    // Detect lifetime
+    let has_lifetime = generics.lifetimes().next().is_some();
+    let lifetime = if has_lifetime {
+        quote! { <'_> }
+    } else {
+        quote! {}
+    };
+
+    // Parse fields
+    let fields = match &data_struct.fields {
+        Fields::Named(fields) => &fields.named,
+        _ => {
+            return Err(syn::Error::new_spanned(
+                input,
+                "LexiconSchema only supports structs with named fields",
+            ));
+        }
+    };
+
+    // Parse serde container attributes (defaults to camelCase)
+    let rename_all = parse_serde_rename_all(&input.attrs)?;
+
+    // Generate field definitions
+    let field_defs = generate_field_definitions(fields, rename_all)?;
+
+    // Generate validation code
+    let validation_code = generate_validation(fields, rename_all)?;
+
+    // Build lexicon_doc() implementation
+    let doc_impl = generate_doc_impl(nsid, type_attrs, &field_defs)?;
+
+    // Determine schema_id (add fragment suffix if needed)
+    let schema_id = if let Some(fragment) = &type_attrs.fragment {
+        let frag_name = if fragment.is_empty() {
+            // Infer from type name
+            name.to_string().to_lower_camel_case()
+        } else {
+            fragment.clone()
+        };
+        quote! {
+            format_smolstr!("{}#{}", #nsid, #frag_name).to_string()
+        }
+    } else {
+        quote! {
+            ::jacquard_common::CowStr::new_static(#nsid)
+        }
+    };
+
+    // Generate trait impl
+    Ok(quote! {
+        impl #generics ::jacquard_lexicon::schema::LexiconSchema for #name #lifetime {
+            fn nsid() -> &'static str {
+                #nsid
+            }
+
+            fn schema_id() -> ::jacquard_common::CowStr<'static> {
+                #schema_id
+            }
+
+            fn lexicon_doc(
+                generator: &mut ::jacquard_lexicon::schema::LexiconGenerator
+            ) -> ::jacquard_lexicon::lexicon::LexiconDoc<'static> {
+                #doc_impl
+            }
+
+            fn validate(&self) -> ::std::result::Result<(), ::jacquard_lexicon::schema::ValidationError> {
+                #validation_code
+            }
+        }
+
+        // Generate inventory submission for Phase 3 discovery
+        ::inventory::submit! {
+            ::jacquard_lexicon::schema::LexiconSchemaRef {
+                nsid: #nsid,
+                provider: || {
+                    let mut generator = ::jacquard_lexicon::schema::LexiconGenerator::new(#nsid);
+                    #name::lexicon_doc(&mut generator)
+                },
+            }
+        }
+    })
+}
+
+struct FieldDef {
+    name: String,          // Rust field name
+    schema_name: String,   // JSON field name (after serde rename)
+    rust_type: Type,       // Rust type
+    lex_type: TokenStream, // LexObjectProperty tokens
+    required: bool,
+}
+
+fn generate_field_definitions(
+    fields: &syn::punctuated::Punctuated<syn::Field, syn::Token![,]>,
+    rename_all: Option<RenameRule>,
+) -> syn::Result<Vec<FieldDef>> {
+    let mut defs = Vec::new();
+
+    for field in fields {
+        let field_name = field.ident.as_ref().unwrap().to_string();
+
+        // Skip extra_data field (added by #[lexicon] attribute macro)
+        if field_name == "extra_data" {
+            continue;
+        }
+
+        // Parse attributes
+        let serde_attrs = parse_serde_attrs(&field.attrs)?;
+        let lex_attrs = parse_field_attrs(&field.attrs)?;
+
+        // Skip if serde(skip)
+        if serde_attrs.skip {
+            continue;
+        }
+
+        // Determine schema name
+        let schema_name = if let Some(rename) = serde_attrs.rename {
+            rename
+        } else if let Some(rule) = rename_all {
+            rule.apply(&field_name)
+        } else {
+            field_name.clone()
+        };
+
+        // Determine if required (Option<T> = optional)
+        let (inner_type, required) = extract_option_inner(&field.ty);
+        let rust_type = inner_type.clone();
+
+        // Generate LexObjectProperty based on type + constraints
+        let lex_type = generate_lex_property(&rust_type, &lex_attrs)?;
+
+        defs.push(FieldDef {
+            name: field_name,
+            schema_name,
+            rust_type,
+            lex_type,
+            required,
+        });
+    }
+
+    Ok(defs)
+}
+
+/// Extract T from Option<T>, return (type, is_required)
+fn extract_option_inner(ty: &Type) -> (&Type, bool) {
+    if let Type::Path(type_path) = ty {
+        if let Some(segment) = type_path.path.segments.last() {
+            if segment.ident == "Option" {
+                if let syn::PathArguments::AngleBracketed(args) = &segment.arguments {
+                    if let Some(syn::GenericArgument::Type(inner)) = args.args.first() {
+                        return (inner, false);
+                    }
+                }
+            }
+        }
+    }
+    (ty, true)
+}
+
+/// Generate LexObjectProperty tokens for a field
+fn generate_lex_property(
+    rust_type: &Type,
+    constraints: &LexiconFieldAttrs,
+) -> syn::Result<TokenStream> {
+    // Try to detect primitive type
+    let lex_type = rust_type_to_lexicon_type(rust_type);
+
+    match lex_type {
+        Some(LexiconPrimitiveType::Boolean) => Ok(quote! {
+            ::jacquard_lexicon::lexicon::LexObjectProperty::Boolean(
+                ::jacquard_lexicon::lexicon::LexBoolean {
+                    description: None,
+                    default: None,
+                    r#const: None,
+                }
+            )
+        }),
+        Some(LexiconPrimitiveType::Integer) => {
+            let minimum = constraints
+                .minimum
+                .map(|v| quote! { Some(#v) })
+                .unwrap_or(quote! { None });
+            let maximum = constraints
+                .maximum
+                .map(|v| quote! { Some(#v) })
+                .unwrap_or(quote! { None });
+
+            Ok(quote! {
+                ::jacquard_lexicon::lexicon::LexObjectProperty::Integer(
+                    ::jacquard_lexicon::lexicon::LexInteger {
+                        description: None,
+                        default: None,
+                        minimum: #minimum,
+                        maximum: #maximum,
+                        r#enum: None,
+                        r#const: None,
+                    }
+                )
+            })
+        }
+        Some(LexiconPrimitiveType::String(format)) => generate_string_property(format, constraints),
+        Some(LexiconPrimitiveType::Bytes) => {
+            let max_length = constraints
+                .max_length
+                .map(|v| quote! { Some(#v) })
+                .unwrap_or(quote! { None });
+            let min_length = constraints
+                .min_length
+                .map(|v| quote! { Some(#v) })
+                .unwrap_or(quote! { None });
+
+            Ok(quote! {
+                ::jacquard_lexicon::lexicon::LexObjectProperty::Bytes(
+                    ::jacquard_lexicon::lexicon::LexBytes {
+                        description: None,
+                        max_length: #max_length,
+                        min_length: #min_length,
+                    }
+                )
+            })
+        }
+        Some(LexiconPrimitiveType::CidLink) => Ok(quote! {
+            ::jacquard_lexicon::lexicon::LexObjectProperty::CidLink(
+                ::jacquard_lexicon::lexicon::LexCidLink {
+                    description: None,
+                }
+            )
+        }),
+        Some(LexiconPrimitiveType::Blob) => Ok(quote! {
+            ::jacquard_lexicon::lexicon::LexObjectProperty::Blob(
+                ::jacquard_lexicon::lexicon::LexBlob {
+                    description: None,
+                    accept: None,
+                    max_size: None,
+                }
+            )
+        }),
+        Some(LexiconPrimitiveType::Unknown) => Ok(quote! {
+            ::jacquard_lexicon::lexicon::LexObjectProperty::Unknown(
+                ::jacquard_lexicon::lexicon::LexUnknown {
+                    description: None,
+                }
+            )
+        }),
+        Some(LexiconPrimitiveType::Array(item_type)) => {
+            let item_prop = generate_array_item(*item_type, constraints)?;
+            let max_length = constraints
+                .max_length
+                .map(|v| quote! { Some(#v) })
+                .unwrap_or(quote! { None });
+            let min_length = constraints
+                .min_length
+                .map(|v| quote! { Some(#v) })
+                .unwrap_or(quote! { None });
+
+            Ok(quote! {
+                ::jacquard_lexicon::lexicon::LexObjectProperty::Array(
+                    ::jacquard_lexicon::lexicon::LexArray {
+                        description: None,
+                        items: #item_prop,
+                        min_length: #min_length,
+                        max_length: #max_length,
+                    }
+                )
+            })
+        }
+        None => {
+            // Not a recognized primitive - check for explicit ref or trait bound
+            if let Some(ref_nsid) = &constraints.explicit_ref {
+                Ok(quote! {
+                    ::jacquard_lexicon::lexicon::LexObjectProperty::Ref(
+                        ::jacquard_lexicon::lexicon::LexRef {
+                            description: None,
+                            r#ref: #ref_nsid.into(),
+                        }
+                    )
+                })
+            } else {
+                // Try to use type's LexiconSchema impl
+                Ok(quote! {
+                    {
+                        // Use the type's schema_id method
+                        let ref_nsid = <#rust_type as ::jacquard_lexicon::schema::LexiconSchema>::schema_id();
+                        ::jacquard_lexicon::lexicon::LexObjectProperty::Ref(
+                            ::jacquard_lexicon::lexicon::LexRef {
+                                description: None,
+                                r#ref: ref_nsid.to_string().into(),
+                            }
+                        )
+                    }
+                })
+            }
+        }
+        _ => Err(syn::Error::new_spanned(
+            rust_type,
+            "unsupported type for lexicon schema generation",
+        )),
+    }
+}
+
+fn generate_array_item(
+    item_type: LexiconPrimitiveType,
+    _constraints: &LexiconFieldAttrs,
+) -> syn::Result<TokenStream> {
+    match item_type {
+        LexiconPrimitiveType::String(format) => {
+            let format_token = string_format_token(format);
+            Ok(quote! {
+                ::jacquard_lexicon::lexicon::LexArrayItem::String(
+                    ::jacquard_lexicon::lexicon::LexString {
+                        description: None,
+                        format: #format_token,
+                        default: None,
+                        min_length: None,
+                        max_length: None,
+                        min_graphemes: None,
+                        max_graphemes: None,
+                        r#enum: None,
+                        r#const: None,
+                        known_values: None,
+                    }
+                )
+            })
+        }
+        LexiconPrimitiveType::Integer => Ok(quote! {
+            ::jacquard_lexicon::lexicon::LexArrayItem::Integer(
+                ::jacquard_lexicon::lexicon::LexInteger {
+                    description: None,
+                    default: None,
+                    minimum: None,
+                    maximum: None,
+                    r#enum: None,
+                    r#const: None,
+                }
+            )
+        }),
+        _ => Ok(quote! {
+            ::jacquard_lexicon::lexicon::LexArrayItem::Unknown(
+                ::jacquard_lexicon::lexicon::LexUnknown {
+                    description: None,
+                }
+            )
+        }),
+    }
+}
+
+fn generate_string_property(
+    format: StringFormat,
+    constraints: &LexiconFieldAttrs,
+) -> syn::Result<TokenStream> {
+    let format_token = string_format_token(format);
+
+    let max_length = constraints
+        .max_length
+        .map(|v| quote! { Some(#v) })
+        .unwrap_or(quote! { None });
+    let max_graphemes = constraints
+        .max_graphemes
+        .map(|v| quote! { Some(#v) })
+        .unwrap_or(quote! { None });
+    let min_length = constraints
+        .min_length
+        .map(|v| quote! { Some(#v) })
+        .unwrap_or(quote! { None });
+    let min_graphemes = constraints
+        .min_graphemes
+        .map(|v| quote! { Some(#v) })
+        .unwrap_or(quote! { None });
+
+    Ok(quote! {
+        ::jacquard_lexicon::lexicon::LexObjectProperty::String(
+            ::jacquard_lexicon::lexicon::LexString {
+                description: None,
+                format: #format_token,
+                default: None,
+                min_length: #min_length,
+                max_length: #max_length,
+                min_graphemes: #min_graphemes,
+                max_graphemes: #max_graphemes,
+                r#enum: None,
+                r#const: None,
+                known_values: None,
+            }
+        )
+    })
+}
+
+fn string_format_token(format: StringFormat) -> TokenStream {
+    match format {
+        StringFormat::Plain => quote! { None },
+        StringFormat::Did => {
+            quote! { Some(::jacquard_lexicon::lexicon::LexStringFormat::Did) }
+        }
+        StringFormat::Handle => {
+            quote! { Some(::jacquard_lexicon::lexicon::LexStringFormat::Handle) }
+        }
+        StringFormat::AtUri => {
+            quote! { Some(::jacquard_lexicon::lexicon::LexStringFormat::AtUri) }
+        }
+        StringFormat::Nsid => {
+            quote! { Some(::jacquard_lexicon::lexicon::LexStringFormat::Nsid) }
+        }
+        StringFormat::Cid => {
+            quote! { Some(::jacquard_lexicon::lexicon::LexStringFormat::Cid) }
+        }
+        StringFormat::Datetime => {
+            quote! { Some(::jacquard_lexicon::lexicon::LexStringFormat::Datetime) }
+        }
+        StringFormat::Language => {
+            quote! { Some(::jacquard_lexicon::lexicon::LexStringFormat::Language) }
+        }
+        StringFormat::Tid => {
+            quote! { Some(::jacquard_lexicon::lexicon::LexStringFormat::Tid) }
+        }
+        StringFormat::RecordKey => {
+            quote! { Some(::jacquard_lexicon::lexicon::LexStringFormat::RecordKey) }
+        }
+        StringFormat::AtIdentifier => {
+            quote! { Some(::jacquard_lexicon::lexicon::LexStringFormat::AtIdentifier) }
+        }
+        StringFormat::Uri => {
+            quote! { Some(::jacquard_lexicon::lexicon::LexStringFormat::Uri) }
+        }
+    }
+}
+
+fn generate_doc_impl(
+    nsid: &str,
+    type_attrs: &LexiconTypeAttrs,
+    field_defs: &[FieldDef],
+) -> syn::Result<TokenStream> {
+    // Build properties map
+    let properties: Vec<_> = field_defs
+        .iter()
+        .map(|def| {
+            let name = &def.schema_name;
+            let lex_type = &def.lex_type;
+            quote! {
+                (#name.into(), #lex_type)
+            }
+        })
+        .collect();
+
+    // Build required array
+    let required: Vec<_> = field_defs
+        .iter()
+        .filter(|def| def.required)
+        .map(|def| {
+            let name = &def.schema_name;
+            quote! { #name.into() }
+        })
+        .collect();
+
+    let required_field = if required.is_empty() {
+        quote! { None }
+    } else {
+        quote! { Some(vec![#(#required),*]) }
+    };
+
+    // Determine user type based on kind
+    let user_type = match type_attrs.kind {
+        Some(LexiconTypeKind::Record) => {
+            let key = type_attrs
+                .key
+                .as_ref()
+                .map(|k| quote! { Some(#k.into()) })
+                .unwrap_or(quote! { None });
+
+            quote! {
+                ::jacquard_lexicon::lexicon::LexUserType::Record(
+                    ::jacquard_lexicon::lexicon::LexRecord {
+                        description: None,
+                        key: #key,
+                        record: ::jacquard_lexicon::lexicon::LexRecordRecord::Object(
+                            ::jacquard_lexicon::lexicon::LexObject {
+                                description: None,
+                                required: #required_field,
+                                nullable: None,
+                                properties: [#(#properties),*].into(),
+                            }
+                        ),
+                    }
+                )
+            }
+        }
+        Some(LexiconTypeKind::Query) => {
+            quote! {
+                ::jacquard_lexicon::lexicon::LexUserType::Query(
+                    ::jacquard_lexicon::lexicon::LexQuery {
+                        description: None,
+                        parameters: Some(::jacquard_lexicon::lexicon::LexObject {
+                            description: None,
+                            required: #required_field,
+                            nullable: None,
+                            properties: [#(#properties),*].into(),
+                        }),
+                        output: None,
+                        errors: None,
+                    }
+                )
+            }
+        }
+        Some(LexiconTypeKind::Procedure) => {
+            quote! {
+                ::jacquard_lexicon::lexicon::LexUserType::Procedure(
+                    ::jacquard_lexicon::lexicon::LexProcedure {
+                        description: None,
+                        input: Some(::jacquard_lexicon::lexicon::LexProcedureIO {
+                            description: None,
+                            encoding: "application/json".into(),
+                            schema: Some(::jacquard_lexicon::lexicon::LexProcedureSchema::Object(
+                                ::jacquard_lexicon::lexicon::LexObject {
+                                    description: None,
+                                    required: #required_field,
+                                    nullable: None,
+                                    properties: [#(#properties),*].into(),
+                                }
+                            )),
+                        }),
+                        output: None,
+                        errors: None,
+                    }
+                )
+            }
+        }
+        _ => {
+            // Default: Object type
+            quote! {
+                ::jacquard_lexicon::lexicon::LexUserType::Object(
+                    ::jacquard_lexicon::lexicon::LexObject {
+                        description: None,
+                        required: #required_field,
+                        nullable: None,
+                        properties: [#(#properties),*].into(),
+                    }
+                )
+            }
+        }
+    };
+
+    Ok(quote! {
+        {
+            let mut defs = ::std::collections::BTreeMap::new();
+            defs.insert("main".into(), #user_type);
+
+            ::jacquard_lexicon::lexicon::LexiconDoc {
+                lexicon: ::jacquard_lexicon::lexicon::Lexicon::Lexicon1,
+                id: #nsid.into(),
+                revision: None,
+                description: None,
+                defs,
+            }
+        }
+    })
+}
+
+fn generate_validation(
+    fields: &syn::punctuated::Punctuated<syn::Field, syn::Token![,]>,
+    rename_all: Option<RenameRule>,
+) -> syn::Result<TokenStream> {
+    let mut checks = Vec::new();
+
+    for field in fields {
+        let field_name = field.ident.as_ref().unwrap();
+        let field_name_str = field_name.to_string();
+
+        // Skip extra_data
+        if field_name_str == "extra_data" {
+            continue;
+        }
+
+        let lex_attrs = parse_field_attrs(&field.attrs)?;
+        let serde_attrs = parse_serde_attrs(&field.attrs)?;
+
+        if serde_attrs.skip {
+            continue;
+        }
+
+        // Get actual field name for errors
+        let display_name = if let Some(rename) = serde_attrs.rename {
+            rename
+        } else if let Some(rule) = rename_all {
+            rule.apply(&field_name_str)
+        } else {
+            field_name_str.clone()
+        };
+
+        // Extract inner type if Option
+        let (inner_type, is_required) = extract_option_inner(&field.ty);
+
+        // Generate checks based on type and constraints
+        let field_checks = generate_field_validation(
+            field_name,
+            &display_name,
+            inner_type,
+            is_required,
+            &lex_attrs,
+        )?;
+
+        checks.extend(field_checks);
+    }
+
+    if checks.is_empty() {
+        Ok(quote! { Ok(()) })
+    } else {
+        Ok(quote! {
+            let mut errors = Vec::new();
+
+            #(#checks)*
+
+            if errors.is_empty() {
+                Ok(())
+            } else if errors.len() == 1 {
+                Err(errors.into_iter().next().unwrap())
+            } else {
+                Err(::jacquard_lexicon::schema::ValidationError::Multiple(errors))
+            }
+        })
+    }
+}
+
+fn generate_field_validation(
+    field_ident: &Ident,
+    display_name: &str,
+    field_type: &Type,
+    is_required: bool,
+    constraints: &LexiconFieldAttrs,
+) -> syn::Result<Vec<TokenStream>> {
+    let mut checks = Vec::new();
+
+    // Determine base type
+    let lex_type = rust_type_to_lexicon_type(field_type);
+
+    // Build accessor for the field value
+    let (value_binding, value_expr) = if is_required {
+        (quote! { let value = &self.#field_ident; }, quote! { value })
+    } else {
+        (
+            quote! {},
+            quote! {
+                match &self.#field_ident {
+                    Some(v) => v,
+                    None => continue,
+                }
+            },
+        )
+    };
+
+    match lex_type {
+        Some(LexiconPrimitiveType::String(_)) => {
+            // String constraints
+            if let Some(max_len) = constraints.max_length {
+                checks.push(quote! {
+                    #value_binding
+                    if #value_expr.len() > #max_len {
+                        errors.push(::jacquard_lexicon::schema::ValidationError::MaxLength {
+                            field: #display_name,
+                            max: #max_len,
+                            actual: #value_expr.len(),
+                        });
+                    }
+                });
+            }
+
+            if let Some(max_graphemes) = constraints.max_graphemes {
+                checks.push(quote! {
+                    #value_binding
+                    let count = ::unicode_segmentation::UnicodeSegmentation::graphemes(
+                        #value_expr.as_ref(),
+                        true
+                    ).count();
+                    if count > #max_graphemes {
+                        errors.push(::jacquard_lexicon::schema::ValidationError::MaxGraphemes {
+                            field: #display_name,
+                            max: #max_graphemes,
+                            actual: count,
+                        });
+                    }
+                });
+            }
+
+            if let Some(min_len) = constraints.min_length {
+                checks.push(quote! {
+                    #value_binding
+                    if #value_expr.len() < #min_len {
+                        errors.push(::jacquard_lexicon::schema::ValidationError::MinLength {
+                            field: #display_name,
+                            min: #min_len,
+                            actual: #value_expr.len(),
+                        });
+                    }
+                });
+            }
+
+            if let Some(min_graphemes) = constraints.min_graphemes {
+                checks.push(quote! {
+                    #value_binding
+                    let count = ::unicode_segmentation::UnicodeSegmentation::graphemes(
+                        #value_expr.as_ref(),
+                        true
+                    ).count();
+                    if count < #min_graphemes {
+                        errors.push(::jacquard_lexicon::schema::ValidationError::MinGraphemes {
+                            field: #display_name,
+                            min: #min_graphemes,
+                            actual: count,
+                        });
+                    }
+                });
+            }
+        }
+        Some(LexiconPrimitiveType::Integer) => {
+            if let Some(maximum) = constraints.maximum {
+                checks.push(quote! {
+                    #value_binding
+                    if *#value_expr > #maximum {
+                        errors.push(::jacquard_lexicon::schema::ValidationError::Maximum {
+                            field: #display_name,
+                            max: #maximum,
+                            actual: *#value_expr,
+                        });
+                    }
+                });
+            }
+
+            if let Some(minimum) = constraints.minimum {
+                checks.push(quote! {
+                    #value_binding
+                    if *#value_expr < #minimum {
+                        errors.push(::jacquard_lexicon::schema::ValidationError::Minimum {
+                            field: #display_name,
+                            min: #minimum,
+                            actual: *#value_expr,
+                        });
+                    }
+                });
+            }
+        }
+        Some(LexiconPrimitiveType::Array(_)) => {
+            if let Some(max_len) = constraints.max_length {
+                checks.push(quote! {
+                    #value_binding
+                    if #value_expr.len() > #max_len {
+                        errors.push(::jacquard_lexicon::schema::ValidationError::MaxLength {
+                            field: #display_name,
+                            max: #max_len,
+                            actual: #value_expr.len(),
+                        });
+                    }
+                });
+            }
+
+            if let Some(min_len) = constraints.min_length {
+                checks.push(quote! {
+                    #value_binding
+                    if #value_expr.len() < #min_len {
+                        errors.push(::jacquard_lexicon::schema::ValidationError::MinLength {
+                            field: #display_name,
+                            min: #min_len,
+                            actual: #value_expr.len(),
+                        });
+                    }
+                });
+            }
+        }
+        _ => {
+            // No built-in validation for this type
+        }
+    }
+
+    Ok(checks)
+}
+
+/// Enum implementation (union support)
+fn impl_for_enum(
+    input: &DeriveInput,
+    type_attrs: &LexiconTypeAttrs,
+    nsid: &str,
+    data_enum: &syn::DataEnum,
+) -> syn::Result<TokenStream> {
+    let name = &input.ident;
+    let generics = &input.generics;
+
+    // Detect lifetime
+    let has_lifetime = generics.lifetimes().next().is_some();
+    let lifetime = if has_lifetime {
+        quote! { <'_> }
+    } else {
+        quote! {}
+    };
+
+    // Check if this is an open union (has #[open_union] attribute)
+    let is_open = has_open_union_attr(&input.attrs);
+
+    // Extract variant refs
+    let mut refs = Vec::new();
+    for variant in &data_enum.variants {
+        // Skip Unknown variant (added by #[open_union] macro)
+        if variant.ident == "Unknown" {
+            continue;
+        }
+
+        // Get NSID for this variant
+        let variant_ref = extract_variant_ref(variant, nsid)?;
+        refs.push(variant_ref);
+    }
+
+    // Generate union def
+    // Only set closed: true for explicitly closed unions (no #[open_union])
+    // Open unions omit the field (defaults to open per spec)
+    let closed_field = if !is_open {
+        quote! { Some(true) }
+    } else {
+        quote! { None }
+    };
+
+    let user_type = quote! {
+        ::jacquard_lexicon::lexicon::LexUserType::Union(
+            ::jacquard_lexicon::lexicon::LexRefUnion {
+                description: None,
+                refs: vec![#(#refs.into()),*],
+                closed: #closed_field,
+            }
+        )
+    };
+
+    Ok(quote! {
+        impl #generics ::jacquard_lexicon::schema::LexiconSchema for #name #lifetime {
+            fn nsid() -> &'static str {
+                #nsid
+            }
+
+            fn schema_id() -> ::jacquard_common::CowStr<'static> {
+                ::jacquard_common::CowStr::new_static(#nsid)
+            }
+
+            fn lexicon_doc(
+                _generator: &mut ::jacquard_lexicon::schema::LexiconGenerator
+            ) -> ::jacquard_lexicon::lexicon::LexiconDoc<'static> {
+                let mut defs = ::std::collections::BTreeMap::new();
+                defs.insert("main".into(), #user_type);
+
+                ::jacquard_lexicon::lexicon::LexiconDoc {
+                    lexicon: ::jacquard_lexicon::lexicon::Lexicon::Lexicon1,
+                    id: #nsid.into(),
+                    revision: None,
+                    description: None,
+                    defs,
+                }
+            }
+        }
+
+        ::inventory::submit! {
+            ::jacquard_lexicon::schema::LexiconSchemaRef {
+                nsid: #nsid,
+                provider: || {
+                    let mut generator = ::jacquard_lexicon::schema::LexiconGenerator::new(#nsid);
+                    #name::lexicon_doc(&mut generator)
+                },
+            }
+        }
+    })
+}
+
+/// Check if type has #[open_union] attribute
+fn has_open_union_attr(attrs: &[Attribute]) -> bool {
+    attrs.iter().any(|attr| attr.path().is_ident("open_union"))
+}
+
+/// Extract NSID ref for a variant
+fn extract_variant_ref(variant: &syn::Variant, base_nsid: &str) -> syn::Result<String> {
+    // Priority 1: Check for #[nsid = "..."] attribute
+    for attr in &variant.attrs {
+        if attr.path().is_ident("nsid") {
+            if let syn::Meta::NameValue(meta) = &attr.meta {
+                if let syn::Expr::Lit(expr_lit) = &meta.value {
+                    if let syn::Lit::Str(lit_str) = &expr_lit.lit {
+                        return Ok(lit_str.value());
+                    }
+                }
+            }
+        }
+    }
+
+    // Priority 2: Check for #[serde(rename = "...")] attribute
+    for attr in &variant.attrs {
+        if !attr.path().is_ident("serde") {
+            continue;
+        }
+
+        let mut rename = None;
+        let _ = attr.parse_nested_meta(|meta| {
+            if meta.path.is_ident("rename") {
+                let value = meta.value()?;
+                let lit: LitStr = value.parse()?;
+                rename = Some(lit.value());
+            }
+            Ok(())
+        });
+
+        if let Some(rename) = rename {
+            return Ok(rename);
+        }
+    }
+
+    // Priority 3: For variants with non-primitive inner types, error
+    // (caller should use #[nsid] or type must impl LexiconSchema)
+    match &variant.fields {
+        Fields::Unit => {
+            // Unit variant - generate fragment ref: baseNsid#variantName
+            let variant_name = variant.ident.to_string().to_lower_camel_case();
+            Ok(format!("{}#{}", base_nsid, variant_name))
+        }
+        Fields::Unnamed(fields) if fields.unnamed.len() == 1 => {
+            let ty = &fields.unnamed.first().unwrap().ty;
+
+            // Check if primitive - if so, error (unions need refs)
+            if let Some(prim) = rust_type_to_lexicon_type(ty) {
+                if is_primitive(&prim) {
+                    return Err(syn::Error::new_spanned(
+                        variant,
+                        "union variants with primitive inner types must use #[nsid] or #[serde(rename)] attribute",
+                    ));
+                }
+            }
+
+            // Non-primitive - error, must have explicit attribute
+            // (we can't call schema_id() at compile time)
+            Err(syn::Error::new_spanned(
+                variant,
+                "union variants with non-primitive types must use #[nsid] or #[serde(rename)] attribute to specify the ref",
+            ))
+        }
+        _ => Err(syn::Error::new_spanned(
+            variant,
+            "union variants must be unit variants or have single unnamed field",
+        )),
+    }
+}
+
+/// Check if a lexicon primitive type is actually a primitive (not a ref-able type)
+fn is_primitive(prim: &LexiconPrimitiveType) -> bool {
+    matches!(
+        prim,
+        LexiconPrimitiveType::Boolean
+            | LexiconPrimitiveType::Integer
+            | LexiconPrimitiveType::String(_)
+            | LexiconPrimitiveType::Bytes
+            | LexiconPrimitiveType::Unknown
+    )
+}

crates/jacquard-lexicon/src/derive_impl/mod.rs

···
 pub mod helpers;
 pub mod into_static;
 pub mod lexicon_attr;
+pub mod lexicon_schema;
 pub mod open_union_attr;
 pub mod xrpc_request;
 
 // Re-export the main entry points
 pub use into_static::impl_derive_into_static;
 pub use lexicon_attr::impl_lexicon;
+pub use lexicon_schema::impl_derive_lexicon_schema;
 pub use open_union_attr::impl_open_union;
 pub use xrpc_request::impl_derive_xrpc_request;

crates/jacquard-lexicon/src/lexicon.rs

···
     CidLink(LexCidLink<'s>),
     // lexUnknown
     Unknown(LexUnknown<'s>),
+    // lexRefUnion
+    Union(LexRefUnion<'s>),
 }
 
 // IntoStatic implementations for all lexicon types
···
             Self::Bytes(x) => LexUserType::Bytes(x.into_static()),
             Self::CidLink(x) => LexUserType::CidLink(x.into_static()),
             Self::Unknown(x) => LexUserType::Unknown(x.into_static()),
+            Self::Union(x) => LexUserType::Union(x.into_static()),
         }
     }
 }

crates/jacquard-lexicon/src/schema.rs

···
     /// The schema ID for this type
     ///
     /// Defaults to NSID. Override for fragments to include `#fragment` suffix.
-    fn schema_id() -> Cow<'static, str> {
-        Cow::Borrowed(Self::nsid())
+    fn schema_id() -> jacquard_common::CowStr<'static> {
+        jacquard_common::CowStr::new_static(Self::nsid())
     }
 
     /// Whether this type should be inlined vs referenced
···
     #[error("invalid NSID: {nsid}")]
     InvalidNsid { nsid: String },
 }
+
+/// Registry entry for schema discovery via inventory
+///
+/// Generated automatically by `#[derive(LexiconSchema)]` to enable runtime schema discovery.
+/// Phase 3 will use this to extract all schemas from a binary.
+pub struct LexiconSchemaRef {
+    /// The NSID for this schema
+    pub nsid: &'static str,
+    /// Function that generates the lexicon document
+    pub provider: fn() -> crate::lexicon::LexiconDoc<'static>,
+}
+
+inventory::collect!(LexiconSchemaRef);
 
 #[cfg(test)]
 mod tests {