feat(data): DataClass (OntoDT/OntoDQ) + TF-Lattice classifier — data-side governance (task #14)

[mdheller]

What (data-side of the vocabulary/governance program; AMG 2.0 deck)

The data-side counterpart to the glossary (#250, biz-side). Where a GlossaryTerm says what a thing means, a DataClass says what its data is — ontologically — so data quality can be inferred and enforced, not asserted.

A DataClass binds four things, fail-closed:

• OntoDT — ontologyClassRef: the datatype-ontology class (capture).
• biz↔data — glossaryTermRef: the business GlossaryTerm it realizes.
• domain — domain ($ref ValidValues): enum / range / regex.
• assignment (optional) — a TF-Lattice wide-and-deep classifier that assigns the class by inference (OntoDQ), a first-class cataloged model: modelRef→ModelManifest, runRef→RunRecord, compute.platform ∈ {ray, tritfabric}, monotonicFeatures (lattice shape constraint), labels that are GlossaryTerm URNs (labels assigned in the glossary).

EntityField gains an optional dataClassRef; the drift-guard enforces field↔class domain conformance (a field can't claim a class it doesn't fit), classifier integrity (glossary labels · cataloged model · Ray/TritFabric compute), and ontological typing. 4 negative vectors; teeth-verified (bad-label, kind-mismatch). make validate ok; dup-$id 346.

This closes the loop your last messages drew: biz glossary ↔ DataClass ↔ EntityField ↔ model catalog ↔ Ray/TritFabric runs ↔ glossary labels. Not auto-merging — for review.

[Copilot]

Pull request overview

Introduces a new DataClass schema and supporting fixtures/examples to formalize the data-side governance node (OntoDT/OntoDQ) and connect it to GlossaryTerm and EntityField, plus a validator + Makefile target to enforce conformance and negative controls.

Changes:

• Added schemas/DataClass.json plus example + negative vectors, and a validator (tools/validate_data_class_examples.py) wired into make validate.
• Extended schemas/EntityField.json with optional dataClassRef and added an EntityField example that binds to a DataClass.
• Added initial contract documentation (specs/data-class-contract.md) and a changelog entry.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
tools/validate_data_class_examples.py	New validator for DataClass/EntityField examples + negative vectors and cross-binding checks.
specs/data-class-contract.md	New short contract doc describing DataClass and its intended invariants.
schemas/EntityField.json	Adds optional dataClassRef for binding fields to DataClass.
schemas/DataClass.json	New DataClass JSON Schema including optional TF-Lattice classifier block.
Makefile	Adds validate-data-class-examples and includes it in validate.
fixtures/data-class/conformance.json	Adds negative vectors for DataClass schema validation.
examples/entity_field.revenue.json	Adds example EntityField bound to a DataClass.
examples/data_class.currency.json	Adds example DataClass with classifier metadata.
CHANGELOG.md	Documents the new DataClass feature in Unreleased.

Suppressed comments (1)

tools/validate_data_class_examples.py:98

• check_field_conformance() is currently fail-open when an EntityField sets dataClassRef but omits validValues: field_kind becomes None and the code records the check as passing. This contradicts the contract text (“field’s validValues must conform…”) and prevents the drift-guard from enforcing domain conformance for such fields.

        field_kind = (fld.get("validValues") or {}).get("kind")
        class_kind = (dc.get("domain") or {}).get("kind")
        if field_kind and class_kind and field_kind != class_kind:
            FAILURES.append(f"{name}: validValues.kind {field_kind!r} does not conform to DataClass {ref} "
                            f"domain kind {class_kind!r}")
        else:
            CHECKS[f"field-conforms:{name}"] = True

[mdheller]

Extended per your review with the two-level classifier architecture: (a) DataClass.classifier is now the per-class LOGISTIC head (one-vs-rest, binary) with a required evalRunRef so each class/glossary-term is individually testable (a class with no eval run is refused); (b) new TableClassifier is the per-table SOFTMAX (n-ary) that MUST align both an lsa-bag-of-words embedding AND a doc2vec-sentence-encoder — the n-ary logit→class representations — as a cataloged model on Ray/TritFabric assigning N DataClasses. Drift-guard enforces both; teeth-verified (missing-doc2vec, missing-evalRunRef). make validate ok.

[mdheller]

Addressed all 4 Copilot findings: (1) classifier now requires runRef + compute (both non-null) — a fully cataloged model on Ray/TritFabric, not partial; (2) EntityField allOf: dataClassRef present ⇒ validValues required (schema-level); (3) validator validates each collection against its intended schema explicitly (not by the instance's type); (4) spec reworded to 'three required + optional assignment'. make validate ok.