ADR-012 — Semantic Constraints Model¶
Status¶
Accepted
Context¶
JSON Schema validates structure (fields exist, types match, enums are respected). But UC-BoK requires a second layer of correctness: relational rules that JSON Schema cannot express. For example:
- "A Business Object that is an Aggregate Root must have a declared lifecycle."
- "A Capability declared as
criticalin a Reference Architecture must be present in that RA's capability map." - "An Event produced by a Process must be declared in the Event catalog."
These rules are called Semantic Constraints and require a separate specification layer.
Decision¶
UC-BoK separates structural validation (JSON Schema) from semantic validation (Semantic Constraints). Semantic Constraints are defined in SPEC-012 and enforced by scripts/validate_ontology.py.
Constraint categories:
| Category | Example Rule |
|---|---|
| Referential integrity | Every capability-id referenced in a Process must exist in capabilities.yaml |
| Lifecycle completeness | Every Aggregate Root must declare at least two lifecycle states |
| Cross-domain consistency | Every Event must have at least one producer Capability |
| Cardinality | A Capability must belong to exactly one Domain |
| Ontology conformance | A Business Object classified as value-object must not appear as a graph root node |
Consequences¶
make validateruns both JSON Schema validation and Semantic Constraint checks.- Catalog changes that pass JSON Schema but fail Semantic Constraints are rejected.
- SPEC-012 is the authoritative source for constraint rules;
validate_ontology.pyimplements them. - Constraint violations are reported with entity ID, constraint rule ID, and remediation guidance.