feat(lance-graph-ontology): PR-bO-16 ZUGFeRD/Factur-X EN16931 via new XsdHydrator

First Tier-C hydrator (per spec) — handles XSD-shaped schemas where
the OwlHydrator's TTL/RDF-XML routes don't apply. ZUGFeRD/Factur-X
EN16931 is the German hybrid PDF/A-3 + XML invoice format aligned
with EU directive EN 16931; the underlying XML schema is UN/CEFACT
CrossIndustryInvoice (CII) v100.

New XsdHydrator (minimal name-extraction shape):
- crates/lance-graph-ontology/src/hydrators/xsd.rs
- Walks every <xs:element>/<xs:complexType>/<xs:simpleType>/<xs:attribute>/
  <xs:attributeGroup> declaration via quick-xml streaming, interns each
  as `{targetNamespace}#{name}` IRIs into the existing ContextBundle
  surface
- Adds quick-xml = "0.37" as a direct dep (already transitively present
  via oxrdfxml)
- collect_xsd_files() walks a directory tree for `.xsd`, sorted for
  stable interning order
- Unit test verifies a tiny inline XSD interns 5 named declarations
- Type-graph semantics (xs:extension base / xs:restriction base) NOT
  resolved into rdfs:subClassOf-equivalent edges — deferred follow-up,
  documented in xsd.rs module docs

bO-16 ZUGFeRD (OGIT::ZUGFERD_V1, slot 30):
- data/ontologies/zugferd/ — 4 XSD files (top-level CII + RAM + QDT +
  UDT) from the Factur-X 1.08 EN16931 profile, plus FACTUR-X_EN16931.sch
  Schematron rules and FACTUR-X_EN16931_codedb.xml code-list database
  (latter two shipped for future SchematronHydrator / CodeListHydrator
  PRs, not hydrated today)
- Source: LandrixSoftware/validator-configuration-zugferd (Apache-2.0)
- entity_count > 200 after hydration of all 4 XSDs
- 17-edge cascade whitelist covers the three CII top-level relational
  containers (ExchangedDocument / ExchangedDocumentContext /
  SupplyChainTradeTransaction) plus the 14 most load-bearing RAM
  predicates (Seller/Buyer TradeParty, TradeAgreement / TradeDelivery /
  TradeSettlement headers, line-item containers, tax / payment terms,
  monetary summation)
- 5 smoke tests verify CII root, RAM types (Header*TradeAgreementType,
  TradePartyType, TradeAddressType, TradeTaxType, ...), all four CII
  namespaces present, edge whitelist registered

LICENSES/ZUGFERD.txt cites Apache-2.0 (LandrixSoftware config) +
UN/CEFACT IP policy for the underlying CII XSDs.

All 98 lance-graph-ontology tests pass; cargo clippy clean; downstream
consumers build clean.

Author: claude

Cargo.lock

@@ -0,0 +1,69 @@
+ZUGFeRD / Factur-X EN 16931 e-invoicing schemas
+================================================
+
+Source
+------
+https://github.com/LandrixSoftware/validator-configuration-zugferd
+Upstream specification: https://www.ferd-net.de/standards/zugferd
+EU directive alignment: EN 16931 (semantic data model of the European
+core invoice).
+
+The schemas are based on the UN/CEFACT Cross-Industry Invoice (CII)
+XML standard, profiled for the Factur-X 1.08 EN16931 conformance
+level — the conformance level required for B2G e-invoicing across
+the EU per the eInvoicing Directive 2014/55/EU.
+
+Authors / publishers
+--------------------
+Validator configuration: Landrix Software (Apache-2.0).
+Underlying CII XSDs: UN/CEFACT (publicly available under UN/CEFACT
+Intellectual Property Policy — royalty-free use for implementation
+permitted).
+ZUGFeRD specification: Forum elektronische Rechnung Deutschland
+(FeRD).
+
+License
+-------
+The validator configuration repository at
+LandrixSoftware/validator-configuration-zugferd is licensed under
+the Apache License, Version 2.0.
+
+Usage in this repository
+------------------------
+data/ontologies/zugferd/ contains the four CII XSD files that make
+up the Factur-X 1.08 EN16931 profile:
+
+  FACTUR-X_EN16931.xsd                                  (top-level)
+  FACTUR-X_EN16931_urn_un_unece_uncefact_data_
+    standard_ReusableAggregateBusinessInformationEntity_100.xsd  (RAM types)
+  FACTUR-X_EN16931_urn_un_unece_uncefact_data_
+    standard_QualifiedDataType_100.xsd                  (QDT)
+  FACTUR-X_EN16931_urn_un_unece_uncefact_data_
+    standard_UnqualifiedDataType_100.xsd                (UDT)
+
+Plus the Schematron business-rule file `FACTUR-X_EN16931.sch` and
+the code-list database `FACTUR-X_EN16931_codedb.xml`. Neither is
+hydrated by the current XsdHydrator — they are shipped for future
+SchematronHydrator (business-rule projection) and CodeListHydrator
+(currency/unit code interning) PRs.
+
+Hydration
+---------
+Hydrated by lance-graph-ontology as the L3 e-invoicing slot
+OGIT::ZUGFERD_V1 via XsdHydrator. The hydrator walks every
+`<xs:element>` / `<xs:complexType>` / `<xs:simpleType>` /
+`<xs:attribute>` / `<xs:attributeGroup>` declaration and interns each
+as `{targetNamespace}#{name}`. Type-graph semantics (`xs:extension
+base="..."` resolution) are NOT projected into rdfs:subClassOf
+edges — that's deferred to a follow-up PR.
+
+Declares inherits_from: Some(OGIT::DOLCE_V1.0). Future alignment:
+- ram:TradePartyType ⊑ fibo-fnd:Party (FIBO Parties module)
+- ram:HeaderTradeSettlementHeaderMonetarySummationType.* ⊑
+  fibo-fnd-acc-cur:MonetaryAmount
+- ram:TradeAddressType ⊑ schema:PostalAddress
+- ram:CrossIndustryInvoiceType ⊑ schema:Invoice
+
+These alignments are NOT baked into the XSDs (they're XML schema
+constraints, not OWL axioms); they're left to downstream consumers
+that need the cross-G projection.

LICENSES/ZUGFERD.txt

@@ -37,6 +37,10 @@ const CANONICAL_SLOTS: &[(&str, u32)] = &[
     // FIBO Foundations and FIBO Business Entities.
     ("FIBOFND", 20),
     ("FIBOBE", 21),
+    // L3 e-invoicing schemas (PR-bO-16). ZUGFeRD/Factur-X is the
+    // German hybrid PDF/A-3+XML invoice format aligned with EN 16931.
+    // Hydrated as IRI-interning over UN/CEFACT CII XSDs via XsdHydrator.
+    ("ZUGFERD", 30),
 ];
 
 fn canonical_slot(token: &str) -> Option<u32> {

crates/lance-graph-contract/build.rs

@@ -22,6 +22,11 @@ oxrdf = "0.3"
 # content here.
 oxrdfxml = "0.2"
 
+# XML parser used by XsdHydrator (ZUGFeRD/UBL/ISO 20022 ship as XSD).
+# Already transitively present via oxrdfxml; we declare it directly so
+# the XSD-name-extraction path doesn't depend on oxrdfxml's version pin.
+quick-xml = "0.37"
+
 # Errors. thiserror keeps the public Error enum readable without serde.
 thiserror = "2"
 

crates/lance-graph-ontology/Cargo.toml

@@ -26,6 +26,8 @@ pub mod provo;
 pub mod qudt;
 pub mod schemaorg;
 pub mod skos;
+pub mod xsd;
+pub mod zugferd;
 
 pub use dolce::{hydrate_dolce, hydrate_dolce_from, hydrate_dolce_from_many};
 pub use fibo::{hydrate_fibo_be, hydrate_fibo_be_from, hydrate_fibo_fnd, hydrate_fibo_fnd_from};
@@ -35,3 +37,5 @@ pub use provo::{hydrate_provo, hydrate_provo_from};
 pub use qudt::{hydrate_qudt, hydrate_qudt_from};
 pub use schemaorg::{hydrate_schemaorg, hydrate_schemaorg_from};
 pub use skos::{hydrate_skos, hydrate_skos_from};
+pub use xsd::{collect_xsd_files, XsdHydrator};
+pub use zugferd::{hydrate_zugferd, hydrate_zugferd_from};

crates/lance-graph-ontology/src/hydrators/mod.rs

@@ -0,0 +1,268 @@
+//! Generic XSD → `ContextBundle` hydrator.
+//!
+//! Where [`super::owl::OwlHydrator`] handles OWL ontologies in Turtle and
+//! RDF/XML serializations, `XsdHydrator` handles XML Schema (XSD) artifacts.
+//! Used by ZUGFeRD / Factur-X (this PR), and intended for UBL, ISO 20022,
+//! and any other e-business schema delivered as XSD.
+//!
+//! Pattern D, minimal-name-extraction shape:
+//!
+//! - Walk every `<xs:element name="...">`, `<xs:complexType name="...">`,
+//!   `<xs:simpleType name="...">`, `<xs:attribute name="...">` and
+//!   `<xs:attributeGroup name="...">` element in each input file.
+//! - Compose each named declaration into a stable IRI by joining the
+//!   nearest `xs:schema/@targetNamespace` with `#{name}` (e.g.
+//!   `urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100#CrossIndustryInvoice`).
+//! - Intern each IRI exactly once into the [`super::owl::OntologySlot`]
+//!   keyed by the chosen `G` slot.
+//!
+//! Out of scope for this PR (deferred to a full XSD type-graph projection
+//! follow-up):
+//!
+//! - `<xs:extension base="...">` / `<xs:restriction base="...">` resolution
+//!   into rdfs:subClassOf-equivalent edges.
+//! - `<xs:element ref="...">` cross-references between files.
+//! - Substitution groups, attribute groups beyond name interning.
+//! - Schematron / business rules — those live in `.sch` files alongside the
+//!   `.xsd` files and would be a separate Schematron hydrator.
+
+use std::collections::HashMap;
+use std::fs;
+use std::path::{Path, PathBuf};
+use std::sync::Arc;
+
+use quick_xml::events::Event;
+use quick_xml::Reader;
+
+use super::owl::{ContextBundle, EntityId, HydrateErr, OntologySlot};
+use crate::registry::OntologyRegistry;
+
+/// XSD hydrator. Reusable for every XSD-shaped business-document schema.
+pub struct XsdHydrator {
+    pub g: u32,
+    pub version: u32,
+    pub domain_name: String,
+    pub inherits_from: Option<u32>,
+    pub starting_entity_id: EntityId,
+}
+
+impl XsdHydrator {
+    /// Multi-file variant. Walks every input XSD, interns named element /
+    /// type / attribute / attributeGroup declarations as
+    /// `{targetNamespace}#{name}` IRIs, and registers a [`ContextBundle`]
+    /// keyed by `self.g`.
+    pub fn hydrate_many(
+        &self,
+        xsd_paths: &[&Path],
+        registry: &OntologyRegistry,
+    ) -> Result<u32, HydrateErr> {
+        let mut iri_to_id: HashMap<String, EntityId> = HashMap::new();
+        let mut next_id: EntityId = self.starting_entity_id;
+
+        let mut intern = |iri: String,
+                          map: &mut HashMap<String, EntityId>,
+                          n: &mut EntityId|
+         -> EntityId {
+            if let Some(&id) = map.get(&iri) {
+                return id;
+            }
+            let id = *n;
+            *n += 1;
+            map.insert(iri, id);
+            id
+        };
+
+        for path in xsd_paths {
+            let bytes = fs::read(path).map_err(|e| HydrateErr::Io {
+                path: path.to_path_buf(),
+                source: e,
+            })?;
+            walk_xsd(path, &bytes, &mut iri_to_id, &mut next_id, &mut intern)?;
+        }
+
+        let entity_count = iri_to_id.len() as u32;
+        let ontology = OntologySlot {
+            entity_count,
+            iri_to_id,
+        };
+        let bundle = ContextBundle {
+            g: self.g,
+            version: self.version,
+            domain_name: self.domain_name.clone(),
+            inherits_from: self.inherits_from,
+            ontology: Some(Arc::new(ontology)),
+            edge_types: Vec::new(),
+        };
+        registry.register_bundle(bundle);
+        Ok(self.g)
+    }
+}
+
+/// Walk one XSD file's events, finding the schema's `targetNamespace` and
+/// interning every named declaration found beneath it.
+fn walk_xsd(
+    path: &Path,
+    bytes: &[u8],
+    iri_to_id: &mut HashMap<String, EntityId>,
+    next_id: &mut EntityId,
+    intern: &mut dyn FnMut(String, &mut HashMap<String, EntityId>, &mut EntityId) -> EntityId,
+) -> Result<(), HydrateErr> {
+    let mut reader = Reader::from_reader(bytes);
+    reader.config_mut().trim_text(true);
+    let mut buf = Vec::new();
+    let mut target_ns: Option<String> = None;
+
+    loop {
+        match reader.read_event_into(&mut buf) {
+            Err(e) => {
+                return Err(HydrateErr::Parse {
+                    path: path.to_path_buf(),
+                    message: format!("XSD: {e}"),
+                });
+            }
+            Ok(Event::Eof) => break,
+            Ok(Event::Start(e)) | Ok(Event::Empty(e)) => {
+                // `e.name()` returns a borrowed view tied to `e`; capture
+                // the local-name bytes into an owned slice to avoid the
+                // temporary-borrow issue under quick-xml 0.37.
+                let qname = e.name();
+                let local: Vec<u8> = local_name(qname.as_ref()).to_vec();
+                if local == b"schema" && target_ns.is_none() {
+                    target_ns = attr_value(&e, b"targetNamespace");
+                } else if matches!(
+                    local.as_slice(),
+                    b"element" | b"complexType" | b"simpleType" | b"attribute" | b"attributeGroup"
+                ) {
+                    if let Some(name) = attr_value(&e, b"name") {
+                        let ns = target_ns.as_deref().unwrap_or("");
+                        let iri = if ns.is_empty() {
+                            // Schema with no targetNamespace: fall back to
+                            // the bare local name so the IRI is still
+                            // resolvable (used only by exotic XSDs; CII
+                            // always declares a targetNamespace).
+                            name
+                        } else {
+                            format!("{ns}#{name}")
+                        };
+                        intern(iri, iri_to_id, next_id);
+                    }
+                }
+            }
+            _ => {}
+        }
+        buf.clear();
+    }
+    Ok(())
+}
+
+fn local_name(qname: &[u8]) -> &[u8] {
+    match qname.iter().position(|b| *b == b':') {
+        Some(i) => &qname[i + 1..],
+        None => qname,
+    }
+}
+
+fn attr_value(e: &quick_xml::events::BytesStart, attr_name: &[u8]) -> Option<String> {
+    for attr in e.attributes().with_checks(false).flatten() {
+        if local_name(attr.key.as_ref()) == attr_name {
+            return std::str::from_utf8(attr.value.as_ref())
+                .ok()
+                .map(|s| s.to_string());
+        }
+    }
+    None
+}
+
+/// Recursively collect every `.xsd` file under `root`, sorted for stable
+/// IRI-interning order.
+pub fn collect_xsd_files(root: &Path) -> Result<Vec<PathBuf>, HydrateErr> {
+    let mut out: Vec<PathBuf> = Vec::new();
+    walk_dir(root, &mut out).map_err(|e| HydrateErr::Io {
+        path: root.to_path_buf(),
+        source: e,
+    })?;
+    out.sort();
+    Ok(out)
+}
+
+fn walk_dir(dir: &Path, out: &mut Vec<PathBuf>) -> std::io::Result<()> {
+    if !dir.exists() {
+        return Err(std::io::Error::new(
+            std::io::ErrorKind::NotFound,
+            format!("XSD directory not found: {}", dir.display()),
+        ));
+    }
+    if !dir.is_dir() {
+        return Ok(());
+    }
+    let mut stack = vec![dir.to_path_buf()];
+    while let Some(d) = stack.pop() {
+        for entry in fs::read_dir(&d)? {
+            let entry = entry?;
+            let p = entry.path();
+            if p.is_dir() {
+                stack.push(p);
+            } else if p.extension().map(|s| s == "xsd").unwrap_or(false) {
+                out.push(p);
+            }
+        }
+    }
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::io::Write;
+    use tempfile::tempdir;
+
+    const TINY_XSD: &str = r#"<?xml version="1.0" encoding="UTF-8"?>
+<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
+           targetNamespace="urn:example:test">
+  <xs:element name="Foo" type="xs:string"/>
+  <xs:complexType name="BarType">
+    <xs:sequence>
+      <xs:element name="baz" type="xs:int"/>
+    </xs:sequence>
+  </xs:complexType>
+  <xs:simpleType name="Quux"/>
+  <xs:attribute name="anAttr" type="xs:string"/>
+</xs:schema>
+"#;
+
+    #[test]
+    fn tiny_xsd_interns_named_declarations() {
+        let dir = tempdir().unwrap();
+        let path = dir.path().join("tiny.xsd");
+        let mut f = std::fs::File::create(&path).unwrap();
+        f.write_all(TINY_XSD.as_bytes()).unwrap();
+        drop(f);
+
+        let reg = OntologyRegistry::new_in_memory();
+        let h = XsdHydrator {
+            g: 9999,
+            version: 1,
+            domain_name: "tiny-xsd".to_string(),
+            inherits_from: None,
+            starting_entity_id: 100,
+        };
+        h.hydrate_many(&[&path], &reg).expect("hydrate tiny XSD");
+
+        let bundle = reg.bundle_for(9999).expect("bundle");
+        // Foo (element) + BarType (complexType) + baz (nested element) +
+        // Quux (simpleType) + anAttr (attribute) = 5 names.
+        assert!(bundle.entity_count() >= 5);
+        assert!(bundle
+            .resolve_iri("urn:example:test#Foo")
+            .is_some());
+        assert!(bundle
+            .resolve_iri("urn:example:test#BarType")
+            .is_some());
+        assert!(bundle
+            .resolve_iri("urn:example:test#baz")
+            .is_some());
+        assert!(bundle
+            .resolve_iri("urn:example:test#anAttr")
+            .is_some());
+    }
+}