codegen cleanup part 1

crates/jacquard-lexicon/src/codegen.rs

···
 
 pub mod lifetime;
 pub mod names;
+pub mod nsid_utils;
 pub mod output;
 pub mod schema_impl;
 pub mod structs;

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

···
 use super::CodeGenerator;
-use crate::lexicon::{LexArrayItem, LexObjectProperty, LexString, LexStringFormat, LexUserType};
+use crate::lexicon::{
+    LexArrayItem, LexObjectProperty, LexPrimitiveArrayItem, LexString, LexStringFormat,
+    LexUserType, LexXrpcParametersProperty,
+};
+
+/// Trait for lexicon types that can determine lifetime requirements
+trait HasLifetime {
+    /// Check if this type needs a lifetime parameter when generated
+    fn needs_lifetime(&self, generator: &CodeGenerator) -> bool;
+}
 
-impl<'c> CodeGenerator<'c> {
-    /// Check if a property type needs a lifetime parameter
-    pub(super) fn property_needs_lifetime(&self, prop: &LexObjectProperty<'static>) -> bool {
-        match prop {
+impl HasLifetime for LexObjectProperty<'_> {
+    fn needs_lifetime(&self, generator: &CodeGenerator) -> bool {
+        match self {
             LexObjectProperty::Boolean(_) | LexObjectProperty::Integer(_) => false,
-            LexObjectProperty::String(s) => self.string_needs_lifetime(s),
+            LexObjectProperty::String(s) => s.needs_lifetime(generator),
             LexObjectProperty::Bytes(_) => false, // Bytes is owned
             LexObjectProperty::CidLink(_)
             | LexObjectProperty::Blob(_)
             | LexObjectProperty::Unknown(_) => true,
-            LexObjectProperty::Array(array) => self.array_item_needs_lifetime(&array.items),
+            LexObjectProperty::Array(array) => array.items.needs_lifetime(generator),
             LexObjectProperty::Object(_) => true, // Nested objects have lifetimes
-            LexObjectProperty::Ref(ref_type) => {
-                // Check if the ref target actually needs a lifetime
-                self.ref_needs_lifetime(&ref_type.r#ref)
-            }
+            LexObjectProperty::Ref(ref_type) => generator.ref_needs_lifetime(&ref_type.r#ref),
             LexObjectProperty::Union(_) => true, // Unions generally have lifetimes
         }
     }
+}
 
-    /// Check if an array item type needs a lifetime parameter
-    pub(super) fn array_item_needs_lifetime(&self, item: &LexArrayItem) -> bool {
-        match item {
+impl HasLifetime for LexArrayItem<'_> {
+    fn needs_lifetime(&self, generator: &CodeGenerator) -> bool {
+        match self {
             LexArrayItem::Boolean(_) | LexArrayItem::Integer(_) => false,
-            LexArrayItem::String(s) => self.string_needs_lifetime(s),
+            LexArrayItem::String(s) => s.needs_lifetime(generator),
             LexArrayItem::Bytes(_) => false,
             LexArrayItem::CidLink(_) | LexArrayItem::Blob(_) | LexArrayItem::Unknown(_) => true,
             LexArrayItem::Object(_) => true, // Nested objects have lifetimes
-            LexArrayItem::Ref(ref_type) => self.ref_needs_lifetime(&ref_type.r#ref),
+            LexArrayItem::Ref(ref_type) => generator.ref_needs_lifetime(&ref_type.r#ref),
             LexArrayItem::Union(_) => true,
         }
     }
+}
 
-    /// Check if a string type needs a lifetime parameter
-    pub(super) fn string_needs_lifetime(&self, s: &LexString) -> bool {
-        match s.format {
+impl HasLifetime for LexString<'_> {
+    fn needs_lifetime(&self, _generator: &CodeGenerator) -> bool {
+        match self.format {
             Some(LexStringFormat::Datetime)
             | Some(LexStringFormat::Language)
             | Some(LexStringFormat::Tid) => false,
             _ => true, // Most string types borrow
         }
     }
+}
 
-    /// Check if a ref needs a lifetime parameter
-    pub(super) fn ref_needs_lifetime(&self, ref_str: &str) -> bool {
-        // Try to resolve the ref
-        if let Some((_doc, def)) = self.corpus.resolve_ref(ref_str) {
-            self.def_needs_lifetime(def)
-        } else {
-            // If we can't resolve it, assume it needs a lifetime (safe default)
-            true
-        }
-    }
-
-    /// Check if a lexicon def needs a lifetime parameter
-    pub(super) fn def_needs_lifetime(&self, def: &LexUserType<'static>) -> bool {
-        match def {
+impl HasLifetime for LexUserType<'_> {
+    fn needs_lifetime(&self, generator: &CodeGenerator) -> bool {
+        match self {
             LexUserType::Record(_) => true,
             LexUserType::Object(_) => true,
             LexUserType::Token(_) => false,
···
                     // Known values enums have Other(CowStr<'a>) variant
                     true
                 } else {
-                    self.string_needs_lifetime(s)
+                    s.needs_lifetime(generator)
                 }
             }
             LexUserType::Integer(_) => false,
             LexUserType::Boolean(_) => false,
             LexUserType::Bytes(_) => false,
             LexUserType::CidLink(_) | LexUserType::Blob(_) | LexUserType::Unknown(_) => true,
-            LexUserType::Array(array) => self.array_item_needs_lifetime(&array.items),
+            LexUserType::Array(array) => array.items.needs_lifetime(generator),
             LexUserType::XrpcQuery(_)
             | LexUserType::XrpcProcedure(_)
             | LexUserType::XrpcSubscription(_) => {
···
             LexUserType::Union(_) => false, // Unions are just refs, no lifetime needed
         }
     }
+}
+
+impl HasLifetime for LexXrpcParametersProperty<'_> {
+    fn needs_lifetime(&self, generator: &CodeGenerator) -> bool {
+        match self {
+            LexXrpcParametersProperty::Boolean(_) | LexXrpcParametersProperty::Integer(_) => false,
+            LexXrpcParametersProperty::String(s) => s.needs_lifetime(generator),
+            LexXrpcParametersProperty::Unknown(_) => true,
+            LexXrpcParametersProperty::Array(arr) => arr.items.needs_lifetime(generator),
+        }
+    }
+}
+
+impl HasLifetime for LexPrimitiveArrayItem<'_> {
+    fn needs_lifetime(&self, generator: &CodeGenerator) -> bool {
+        match self {
+            LexPrimitiveArrayItem::Boolean(_) | LexPrimitiveArrayItem::Integer(_) => false,
+            LexPrimitiveArrayItem::String(s) => s.needs_lifetime(generator),
+            LexPrimitiveArrayItem::Unknown(_) => true,
+        }
+    }
+}
+
+impl<'c> CodeGenerator<'c> {
+    /// Check if a property type needs a lifetime parameter
+    pub(super) fn property_needs_lifetime(&self, prop: &LexObjectProperty<'_>) -> bool {
+        prop.needs_lifetime(self)
+    }
+
+    /// Check if an array item type needs a lifetime parameter
+    pub(super) fn array_item_needs_lifetime(&self, item: &LexArrayItem<'_>) -> bool {
+        item.needs_lifetime(self)
+    }
+
+    /// Check if a string type needs a lifetime parameter
+    pub(super) fn string_needs_lifetime(&self, s: &LexString<'_>) -> bool {
+        s.needs_lifetime(self)
+    }
+
+    /// Check if a ref needs a lifetime parameter
+    pub(super) fn ref_needs_lifetime(&self, ref_str: &str) -> bool {
+        // Try to resolve the ref
+        if let Some((_doc, def)) = self.corpus.resolve_ref(ref_str) {
+            def.needs_lifetime(self)
+        } else {
+            // If we can't resolve it, assume it needs a lifetime (safe default)
+            true
+        }
+    }
+
+    /// Check if a lexicon def needs a lifetime parameter
+    pub(super) fn def_needs_lifetime(&self, def: &LexUserType<'_>) -> bool {
+        def.needs_lifetime(self)
+    }
 
     /// Check if xrpc params need a lifetime parameter
     pub(super) fn params_need_lifetime(
         &self,
-        params: &crate::lexicon::LexXrpcParameters<'static>,
+        params: &crate::lexicon::LexXrpcParameters<'_>,
     ) -> bool {
-        params.properties.values().any(|prop| {
-            use crate::lexicon::LexXrpcParametersProperty;
-            match prop {
-                LexXrpcParametersProperty::Boolean(_) | LexXrpcParametersProperty::Integer(_) => {
-                    false
-                }
-                LexXrpcParametersProperty::String(s) => self.string_needs_lifetime(s),
-                LexXrpcParametersProperty::Unknown(_) => true,
-                LexXrpcParametersProperty::Array(arr) => {
-                    use crate::lexicon::LexPrimitiveArrayItem;
-                    match &arr.items {
-                        LexPrimitiveArrayItem::Boolean(_) | LexPrimitiveArrayItem::Integer(_) => {
-                            false
-                        }
-                        LexPrimitiveArrayItem::String(s) => self.string_needs_lifetime(s),
-                        LexPrimitiveArrayItem::Unknown(_) => true,
-                    }
-                }
-            }
-        })
+        params
+            .properties
+            .values()
+            .any(|prop| prop.needs_lifetime(self))
     }
 }

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

···
+use super::nsid_utils::NsidPath;
 use super::utils::sanitize_name;
 use super::CodeGenerator;
 use heck::{ToPascalCase, ToSnakeCase};
···
     fn def_to_base_type_name(&self, nsid: &str, def_name: &str) -> String {
         if def_name == "main" {
             // Use last segment of NSID
-            let base_name = nsid.split('.').last().unwrap().to_pascal_case();
+            let nsid_path = NsidPath::parse(nsid);
+            let base_name = nsid_path.last_segment().to_pascal_case();
 
             // Check if any other def would collide with this name
             if let Some(doc) = self.corpus.get(nsid) {
···
         // Add contextual prefix to avoid collision
         if def_name == "main" {
             // Use second-to-last NSID segment for main defs
-            let parts: Vec<_> = nsid.split('.').collect();
+            let nsid_path = NsidPath::parse(nsid);
+            let parts = nsid_path.segments();
             if parts.len() >= 2 {
                 format!("{}{}", parts[parts.len() - 2].to_pascal_case(), base_name)
             } else {
···
     /// - `app.bsky.feed.post` → `app_bsky/feed/post.rs`
     /// - `com.atproto.label.defs` → `com_atproto/label.rs` (defs go in parent)
     pub(super) fn nsid_to_file_path(&self, nsid: &str) -> std::path::PathBuf {
-        let parts: Vec<&str> = nsid.split('.').collect();
+        let nsid_path = NsidPath::parse(nsid);
+        let parts = nsid_path.segments();
 
         if parts.len() < 2 {
             // Shouldn't happen with valid NSIDs, but handle gracefully
             return format!("{}.rs", sanitize_name(parts[0])).into();
         }
 
-        let last = parts.last().unwrap();
+        let last = nsid_path.last_segment();
 
-        if *last == "defs" && parts.len() >= 3 {
+        if nsid_path.is_defs() && parts.len() >= 3 {
             // defs go in parent module: com.atproto.label.defs → com_atproto/label.rs
             let first_two = format!("{}_{}", sanitize_name(parts[0]), sanitize_name(parts[1]));
             if parts.len() == 3 {

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

···
+//! Utilities for parsing and working with NSIDs and refs
+
+/// Parsed NSID components for easier manipulation
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct NsidPath<'a> {
+    nsid: &'a str,
+    segments: Vec<&'a str>,
+}
+
+impl<'a> NsidPath<'a> {
+    /// Parse an NSID into its component segments
+    pub fn parse(nsid: &'a str) -> Self {
+        let segments: Vec<&str> = nsid.split('.').collect();
+        Self { nsid, segments }
+    }
+
+    /// Get the namespace (first two segments joined with '.')
+    /// Returns "com.atproto" from "com.atproto.repo.strongRef"
+    pub fn namespace(&self) -> String {
+        if self.segments.len() >= 2 {
+            format!("{}.{}", self.segments[0], self.segments[1])
+        } else {
+            self.nsid.to_string()
+        }
+    }
+
+    /// Get the last segment of the NSID
+    pub fn last_segment(&self) -> &str {
+        self.segments.last().copied().unwrap_or(self.nsid)
+    }
+
+    /// Get all segments except the last
+    pub fn parent_segments(&self) -> &[&str] {
+        if self.segments.is_empty() {
+            &[]
+        } else {
+            &self.segments[..self.segments.len() - 1]
+        }
+    }
+
+    /// Check if this is a "defs" NSID (ends with "defs")
+    pub fn is_defs(&self) -> bool {
+        self.last_segment() == "defs"
+    }
+
+    /// Get all segments
+    pub fn segments(&self) -> &[&str] {
+        &self.segments
+    }
+
+    /// Get the original NSID string
+    pub fn as_str(&self) -> &str {
+        self.nsid
+    }
+
+    /// Get number of segments
+    pub fn len(&self) -> usize {
+        self.segments.len()
+    }
+
+    /// Check if empty (should not happen with valid NSIDs)
+    pub fn is_empty(&self) -> bool {
+        self.segments.is_empty()
+    }
+}
+
+/// Parsed reference with NSID and optional fragment
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct RefPath<'a> {
+    nsid: &'a str,
+    def: &'a str,
+}
+
+impl<'a> RefPath<'a> {
+    /// Parse a reference string, normalizing it based on current NSID context
+    pub fn parse(ref_str: &'a str, current_nsid: Option<&'a str>) -> Self {
+        if let Some(fragment) = ref_str.strip_prefix('#') {
+            // Local ref: #option → use current_nsid
+            let nsid = current_nsid.unwrap_or("");
+            Self {
+                nsid,
+                def: fragment,
+            }
+        } else if let Some((nsid, def)) = ref_str.split_once('#') {
+            // Full ref with fragment: nsid#def
+            Self { nsid, def }
+        } else {
+            // Full ref without fragment: nsid (implicit "main")
+            Self {
+                nsid: ref_str,
+                def: "main",
+            }
+        }
+    }
+
+    /// Get the NSID portion of the ref
+    pub fn nsid(&self) -> &str {
+        self.nsid
+    }
+
+    /// Get the def name (fragment) portion of the ref
+    pub fn def(&self) -> &str {
+        self.def
+    }
+
+    /// Check if this is a local ref (was parsed from #fragment)
+    pub fn is_local(&self, current_nsid: &str) -> bool {
+        self.nsid == current_nsid && self.def != "main"
+    }
+
+    /// Get the full ref string (nsid#def)
+    pub fn full_ref(&self) -> String {
+        if self.def == "main" {
+            self.nsid.to_string()
+        } else {
+            format!("{}#{}", self.nsid, self.def)
+        }
+    }
+
+    /// Normalize a local ref by prepending the current NSID if needed
+    /// Returns the normalized ref string suitable for corpus lookup
+    pub fn normalize(ref_str: &str, current_nsid: &str) -> String {
+        if ref_str.starts_with('#') {
+            format!("{}{}", current_nsid, ref_str)
+        } else {
+            ref_str.to_string()
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_nsid_path_parse() {
+        let path = NsidPath::parse("com.atproto.repo.strongRef");
+        assert_eq!(path.segments(), &["com", "atproto", "repo", "strongRef"]);
+        assert_eq!(path.namespace(), "com.atproto");
+        assert_eq!(path.last_segment(), "strongRef");
+        assert_eq!(path.parent_segments(), &["com", "atproto", "repo"]);
+        assert!(!path.is_defs());
+    }
+
+    #[test]
+    fn test_nsid_path_defs() {
+        let path = NsidPath::parse("com.atproto.label.defs");
+        assert!(path.is_defs());
+        assert_eq!(path.last_segment(), "defs");
+    }
+
+    #[test]
+    fn test_ref_path_local() {
+        let ref_path = RefPath::parse("#option", Some("com.example.foo"));
+        assert_eq!(ref_path.nsid(), "com.example.foo");
+        assert_eq!(ref_path.def(), "option");
+        assert!(ref_path.is_local("com.example.foo"));
+        assert_eq!(ref_path.full_ref(), "com.example.foo#option");
+    }
+
+    #[test]
+    fn test_ref_path_with_fragment() {
+        let ref_path = RefPath::parse("com.example.foo#bar", None);
+        assert_eq!(ref_path.nsid(), "com.example.foo");
+        assert_eq!(ref_path.def(), "bar");
+        assert!(!ref_path.is_local("com.other.baz"));
+        assert_eq!(ref_path.full_ref(), "com.example.foo#bar");
+    }
+
+    #[test]
+    fn test_ref_path_implicit_main() {
+        let ref_path = RefPath::parse("com.example.foo", None);
+        assert_eq!(ref_path.nsid(), "com.example.foo");
+        assert_eq!(ref_path.def(), "main");
+        assert_eq!(ref_path.full_ref(), "com.example.foo");
+    }
+
+    #[test]
+    fn test_ref_path_normalize() {
+        assert_eq!(
+            RefPath::normalize("#option", "com.example.foo"),
+            "com.example.foo#option"
+        );
+        assert_eq!(
+            RefPath::normalize("com.other.bar#baz", "com.example.foo"),
+            "com.other.bar#baz"
+        );
+    }
+}

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

···
 use quote::quote;
 use std::collections::{BTreeMap, BTreeSet, HashMap, HashSet};
 
+use super::nsid_utils::NsidPath;
 use super::utils::{make_ident, sanitize_name};
 use super::CodeGenerator;
 
···
 
         // Collect all namespaces from the corpus (first two segments of each NSID)
         for (nsid, _doc) in self.corpus.iter() {
-            let parts: Vec<_> = nsid.as_str().splitn(3, '.').collect();
-            let namespace = if parts.len() >= 2 {
-                format!("{}.{}", parts[0], parts[1])
-            } else {
-                nsid.to_string()
-            };
+            let nsid_path = NsidPath::parse(nsid.as_str());
+            let namespace = nsid_path.namespace();
             all_namespaces.insert(namespace);
         }
 

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

···
 use proc_macro2::TokenStream;
 use quote::quote;
 
+use super::nsid_utils::{NsidPath, RefPath};
 use super::CodeGenerator;
 use super::utils::{make_ident, value_to_variant_name};
 
···
         let enum_ident = syn::Ident::new(union_name, proc_macro2::Span::call_site());
 
         // Extract namespace prefix from current NSID (first two segments: "sh.weaver" from "sh.weaver.embed.recordWithMedia")
-        let parts: Vec<_> = current_nsid.splitn(3, '.').collect();
-        let current_namespace = if parts.len() >= 2 {
-            format!("{}.{}", parts[0], parts[1])
-        } else {
-            current_nsid.to_string()
-        };
+        let current_nsid_path = NsidPath::parse(current_nsid);
+        let current_namespace = current_nsid_path.namespace();
 
         // First pass: collect all variant names and detect collisions
         #[derive(Debug)]
···
         let mut variant_infos = Vec::new();
         for ref_str in refs {
             // Normalize local refs (starting with #) by prepending current NSID
-            let normalized_ref = if ref_str.starts_with('#') {
-                format!("{}{}", current_nsid, ref_str)
-            } else {
-                ref_str.to_string()
-            };
+            let normalized_ref = RefPath::normalize(ref_str, current_nsid);
 
             // Parse ref to get NSID and def name
-            let (ref_nsid_str, ref_def) =
-                if let Some((nsid, fragment)) = normalized_ref.split_once('#') {
-                    (nsid, fragment)
-                } else {
-                    (normalized_ref.as_str(), "main")
-                };
+            let ref_path = RefPath::parse(&normalized_ref, None);
+            let ref_nsid_str = ref_path.nsid();
+            let ref_def = ref_path.def();
 
             // Skip unknown refs - they'll be handled by Unknown variant
             if !self.corpus.ref_exists(&normalized_ref) {
···
 
             // Track namespace dependency for foreign refs
             if !info.is_current_namespace {
-                let parts: Vec<_> = info.ref_nsid.splitn(3, '.').collect();
-                let foreign_namespace = if parts.len() >= 2 {
-                    format!("{}.{}", parts[0], parts[1])
-                } else {
-                    info.ref_nsid.to_string()
-                };
+                let ref_nsid_path = NsidPath::parse(&info.ref_nsid);
+                let foreign_namespace = ref_nsid_path.namespace();
                 self.namespace_deps
                     .borrow_mut()
                     .entry(current_namespace.clone())
···
             // Disambiguate: add second NSID segment prefix only to foreign refs when there's a collision
             let variant_name = if has_collision && !info.is_current_namespace {
                 // Get second segment (namespace identifier: "bsky" from "app.bsky.embed.images")
-                let segments: Vec<&str> = info.ref_nsid.split('.').collect();
+                let ref_nsid_path = NsidPath::parse(&info.ref_nsid);
+                let segments = ref_nsid_path.segments();
                 let prefix = if segments.len() >= 2 {
                     segments[1].to_pascal_case()
                 } else {

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

···
 use proc_macro2::TokenStream;
 use quote::quote;
 
+use super::nsid_utils::{NsidPath, RefPath};
 use super::CodeGenerator;
 
 impl<'c> CodeGenerator<'c> {
···
                     };
 
                     // Parse ref to get type name
-                    let (ref_nsid, ref_def) =
-                        if let Some((nsid_part, fragment)) = ref_str.split_once('#') {
-                            (nsid_part, fragment)
-                        } else {
-                            (ref_str.as_str(), "main")
-                        };
-                    let ref_type_name = self.def_to_type_name(ref_nsid, ref_def);
+                    let ref_path = RefPath::parse(&ref_str, None);
+                    let ref_type_name = self.def_to_type_name(ref_path.nsid(), ref_path.def());
 
                     // If self-referential, keep union for indirection (variants are boxed)
                     if ref_type_name == parent_type_name {
···
         use super::utils::sanitize_name;
         use crate::error::CodegenError;
 
-        // Parse NSID and fragment
-        let (ref_nsid, ref_def) = if let Some((nsid, fragment)) = ref_str.split_once('#') {
-            (nsid, fragment)
-        } else {
-            (ref_str, "main")
-        };
+        // Parse ref to get NSID and def
+        let ref_path = RefPath::parse(ref_str, None);
+        let ref_nsid = ref_path.nsid();
+        let ref_def = ref_path.def();
 
         // Check if ref exists
         if !self.corpus.ref_exists(ref_str) {
···
             return Ok(quote! { jacquard_common::types::value::Data<'a> });
         }
 
+        // Parse NSID into components
+        let nsid_path = NsidPath::parse(ref_nsid);
+        let parts = nsid_path.segments();
+        let last_segment = nsid_path.last_segment();
+
         // Convert NSID to module path
         // com.atproto.repo.strongRef -> com_atproto::repo::strong_ref::StrongRef
         // app.bsky.richtext.facet -> app_bsky::richtext::facet::Facet
         // app.bsky.actor.defs#nux -> app_bsky::actor::Nux (defs go in parent module)
-        let parts: Vec<&str> = ref_nsid.split('.').collect();
-        let last_segment = parts.last().unwrap();
-
         let type_name = self.def_to_type_name(ref_nsid, ref_def);
 
-        let path_str = if *last_segment == "defs" && parts.len() >= 3 {
+        let path_str = if nsid_path.is_defs() && parts.len() >= 3 {
             // defs types go in parent module
             let first_two = format!("{}_{}", sanitize_name(parts[0]), sanitize_name(parts[1]));
             if parts.len() == 3 {

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

···
 use proc_macro2::TokenStream;
 use quote::quote;
 
+use super::nsid_utils::{NsidPath, RefPath};
 use super::CodeGenerator;
 use super::utils::make_ident;
 
···
                     let ref_str_s = ref_str.as_ref();
 
                     // Normalize local refs (starting with #) by prepending current NSID
-                    let normalized_ref = if ref_str.starts_with('#') {
-                        format!("{}{}", nsid, ref_str)
-                    } else {
-                        ref_str.to_string()
-                    };
+                    let normalized_ref = RefPath::normalize(ref_str, nsid);
 
                     // Parse ref to get NSID and def name
-                    let (ref_nsid, ref_def) =
-                        if let Some((nsid_part, fragment)) = normalized_ref.split_once('#') {
-                            (nsid_part, fragment)
-                        } else {
-                            (normalized_ref.as_str(), "main")
-                        };
+                    let ref_path = RefPath::parse(&normalized_ref, None);
+                    let ref_nsid = ref_path.nsid();
+                    let ref_def = ref_path.def();
 
                     let variant_name = if ref_def == "main" {
-                        ref_nsid.split('.').last().unwrap().to_pascal_case()
+                        let ref_nsid_path = NsidPath::parse(ref_nsid);
+                        ref_nsid_path.last_segment().to_pascal_case()
                     } else {
                         ref_def.to_pascal_case()
                     };

crates/jacquard-lexicon/src/corpus.rs

···
+use crate::codegen::nsid_utils::RefPath;
 use crate::error::Result;
 use crate::lexicon::{LexUserType, LexiconDoc};
 use jacquard_common::{into_static::IntoStatic, smol_str::SmolStr};
···
         &self,
         ref_str: &str,
     ) -> Option<(&LexiconDoc<'static>, &LexUserType<'static>)> {
-        let (nsid, def_name) = if let Some((nsid, fragment)) = ref_str.split_once('#') {
-            (nsid, fragment)
-        } else {
-            (ref_str, "main")
-        };
-
-        let doc = self.get(nsid)?;
-        let def = doc.defs.get(def_name)?;
+        let ref_path = RefPath::parse(ref_str, None);
+        let doc = self.get(ref_path.nsid())?;
+        let def = doc.defs.get(ref_path.def())?;
         Some((doc, def))
     }
 

crates/jacquard-lexicon/src/validation.rs

···
 //! This module provides infrastructure for validating untyped `Data` values against
 //! lexicon schemas, enabling partial deserialization, debugging, and schema migration.
 
+use crate::codegen::nsid_utils::RefPath;
+use crate::lexicon::{LexArrayItem, LexObjectProperty};
 use crate::schema::SchemaRegistry;
 use cid::Cid as IpldCid;
 use dashmap::DashMap;
···
     Ok(IpldCid::new_v1(0x71, multihash))
 }
 
+/// Trait for converting lexicon types to object properties
+///
+/// This enables type-safe conversion between array items and object properties
+/// for unified validation logic.
+trait IntoObjectProperty<'a> {
+    /// Convert this type to an equivalent object property
+    fn into_object_property(self) -> LexObjectProperty<'a>;
+}
+
+impl<'a> IntoObjectProperty<'a> for LexArrayItem<'a> {
+    fn into_object_property(self) -> LexObjectProperty<'a> {
+        match self {
+            LexArrayItem::String(s) => LexObjectProperty::String(s),
+            LexArrayItem::Integer(i) => LexObjectProperty::Integer(i),
+            LexArrayItem::Boolean(b) => LexObjectProperty::Boolean(b),
+            LexArrayItem::Object(o) => LexObjectProperty::Object(o),
+            LexArrayItem::Unknown(u) => LexObjectProperty::Unknown(u),
+            LexArrayItem::Bytes(b) => LexObjectProperty::Bytes(b),
+            LexArrayItem::CidLink(c) => LexObjectProperty::CidLink(c),
+            LexArrayItem::Blob(b) => LexObjectProperty::Blob(b),
+            LexArrayItem::Ref(r) => LexObjectProperty::Ref(r),
+            LexArrayItem::Union(u) => LexObjectProperty::Union(u),
+        }
+    }
+}
+
 /// Result of validating Data against a schema
 ///
 /// Distinguishes between structural errors (type mismatches, missing fields) and
···
     }
 }
 
-/// Normalize a ref string to (nsid, def_name)
-fn normalize_ref(ref_str: &str, current_nsid: &str) -> (String, String) {
-    if let Some(fragment) = ref_str.strip_prefix('#') {
-        // #option -> (current_nsid, "option")
-        (current_nsid.to_string(), fragment.to_string())
-    } else if let Some((nsid, def)) = ref_str.split_once('#') {
-        // com.example.foo#bar -> ("com.example.foo", "bar")
-        (nsid.to_string(), def.to_string())
-    } else {
-        // com.example.foo -> ("com.example.foo", "main")
-        (ref_str.to_string(), "main".to_string())
-    }
-}
 
 /// Validate data against a lexicon def
 fn validate_def(
···
 
             // Try to match against refs
             for variant_ref in &u.refs {
-                let (variant_nsid, variant_def) =
-                    normalize_ref(variant_ref.as_ref(), &ctx.current_nsid);
-                let full_variant = format!("{}#{}", variant_nsid, variant_def);
+                let ref_path = RefPath::parse(variant_ref.as_ref(), Some(&ctx.current_nsid));
+                let variant_nsid = ref_path.nsid().to_string();
+                let variant_def = ref_path.def().to_string();
+                let full_variant = ref_path.full_ref();
 
                 // Match by full ref or just nsid
                 if type_str == full_variant || type_str == variant_nsid {
···
             }
 
             // Normalize ref
-            let (ref_nsid, ref_def) = normalize_ref(r.r#ref.as_ref(), &ctx.current_nsid);
-            let full_ref = format!("{}#{}", ref_nsid, ref_def);
+            let ref_path = RefPath::parse(r.r#ref.as_ref(), Some(&ctx.current_nsid));
+            let ref_nsid = ref_path.nsid().to_string();
+            let ref_def = ref_path.def().to_string();
+            let full_ref = ref_path.full_ref();
 
             // Cycle detection
             if ctx.ref_stack.contains(&full_ref) {
···
 fn validate_array_item(
     path: &mut ValidationPath,
     data: &Data,
-    item_schema: &crate::lexicon::LexArrayItem,
+    item_schema: &LexArrayItem,
     registry: &SchemaRegistry,
     ctx: &mut ValidationContext,
 ) -> Vec<StructuralError> {
-    use crate::lexicon::LexArrayItem;
-
-    match item_schema {
-        LexArrayItem::String(s) => validate_property(
-            path,
-            data,
-            &crate::lexicon::LexObjectProperty::String(s.clone()),
-            registry,
-            ctx,
-        ),
-        LexArrayItem::Integer(i) => validate_property(
-            path,
-            data,
-            &crate::lexicon::LexObjectProperty::Integer(i.clone()),
-            registry,
-            ctx,
-        ),
-        LexArrayItem::Boolean(b) => validate_property(
-            path,
-            data,
-            &crate::lexicon::LexObjectProperty::Boolean(b.clone()),
-            registry,
-            ctx,
-        ),
-        LexArrayItem::Object(o) => validate_property(
-            path,
-            data,
-            &crate::lexicon::LexObjectProperty::Object(o.clone()),
-            registry,
-            ctx,
-        ),
-        LexArrayItem::Unknown(u) => validate_property(
-            path,
-            data,
-            &crate::lexicon::LexObjectProperty::Unknown(u.clone()),
-            registry,
-            ctx,
-        ),
-        LexArrayItem::Bytes(b) => validate_property(
-            path,
-            data,
-            &crate::lexicon::LexObjectProperty::Bytes(b.clone()),
-            registry,
-            ctx,
-        ),
-        LexArrayItem::CidLink(c) => validate_property(
-            path,
-            data,
-            &crate::lexicon::LexObjectProperty::CidLink(c.clone()),
-            registry,
-            ctx,
-        ),
-        LexArrayItem::Blob(b) => validate_property(
-            path,
-            data,
-            &crate::lexicon::LexObjectProperty::Blob(b.clone()),
-            registry,
-            ctx,
-        ),
-        LexArrayItem::Ref(r) => validate_property(
-            path,
-            data,
-            &crate::lexicon::LexObjectProperty::Ref(r.clone()),
-            registry,
-            ctx,
-        ),
-        LexArrayItem::Union(u) => validate_property(
-            path,
-            data,
-            &crate::lexicon::LexObjectProperty::Union(u.clone()),
-            registry,
-            ctx,
-        ),
-    }
+    validate_property(
+        path,
+        data,
+        &item_schema.clone().into_object_property(),
+        registry,
+        ctx,
+    )
 }
 
 // ============================================================================
···
 
         LexObjectProperty::Ref(r) => {
             // Follow ref and check constraints
-            let (ref_nsid, ref_def) = normalize_ref(r.r#ref.as_ref(), current_nsid);
+            let ref_path = RefPath::parse(r.r#ref.as_ref(), Some(current_nsid));
+            let ref_nsid = ref_path.nsid();
+            let ref_def = ref_path.def();
 
-            if registry.get_def(&ref_nsid, &ref_def).is_some() {
-                validate_constraints_impl(path, data, &ref_nsid, &ref_def, registry)
+            if registry.get_def(ref_nsid, ref_def).is_some() {
+                validate_constraints_impl(path, data, ref_nsid, ref_def, registry)
             } else {
                 Vec::new()
             }
···
 fn check_array_item_constraints(
     path: &mut ValidationPath,
     data: &Data,
-    item_schema: &crate::lexicon::LexArrayItem,
+    item_schema: &LexArrayItem,
     current_nsid: &str,
     registry: &SchemaRegistry,
 ) -> Vec<ConstraintError> {
-    use crate::lexicon::LexArrayItem;
-
-    match item_schema {
-        LexArrayItem::String(s) => check_property_constraints(
-            path,
-            data,
-            &crate::lexicon::LexObjectProperty::String(s.clone()),
-            current_nsid,
-            registry,
-        ),
-        LexArrayItem::Integer(i) => check_property_constraints(
-            path,
-            data,
-            &crate::lexicon::LexObjectProperty::Integer(i.clone()),
-            current_nsid,
-            registry,
-        ),
-        LexArrayItem::Object(o) => check_property_constraints(
-            path,
-            data,
-            &crate::lexicon::LexObjectProperty::Object(o.clone()),
-            current_nsid,
-            registry,
-        ),
-        LexArrayItem::Ref(r) => check_property_constraints(
-            path,
-            data,
-            &crate::lexicon::LexObjectProperty::Ref(r.clone()),
-            current_nsid,
-            registry,
-        ),
-        // Other array item types don't have constraints
-        _ => Vec::new(),
-    }
+    check_property_constraints(
+        path,
+        data,
+        &item_schema.clone().into_object_property(),
+        current_nsid,
+        registry,
+    )
 }
 
 #[cfg(test)]