ADR-015 — Semantic Model Specification¶

Status: Accepted

Date: 2026-07-05

Owner: Architecture Board

Decision Type: Normative Extension

Supersedes: —

Complements: ADR-003 (Canonical Knowledge Model), ADR-004 (Ontology Modularization)

Context¶

UC-BoK v0.6-alpha is the first release where all major catalog layers — Business Objects, Capabilities, Processes, Domains, Applications, APIs, Events — have rich detail pages with full bidirectional cross-references.

The review of v0.6-alpha identified a gap.

The catalog has 17 canonical relationship verbs (defined in specifications/007-ontology/relationships.md). These verbs are used consistently across 46 Business Objects. But the vocabulary specification stops at naming — it does not declare:

• Cardinality: how many targets a given verb implies (1:1, 1:N, N:M, 0:N)
• Lifecycle coupling: whether deleting the source invalidates the target
• Composition grammar: which BO classifications may compose which, through which verbs
• Dependency types: whether a relationship is structurally, behaviorally, or temporally coupled

Additionally, the catalog has two rule catalogs — constraints.yaml and validation-rules.yaml — that are frequently confused in practice. Authors writing new catalog entries often placed domain invariants into validation-rules and process guards into constraints.

The gap in one sentence¶

The vocabulary existed. The grammar did not.

A vocabulary says: these verbs exist.
A grammar says: these verbs have these properties and these constraints on their use.

Without a grammar, the graph is navigable but not formally reasoned-about. Relationships can be added inconsistently. The distinction between "always true" and "true at runtime" is advisory at best.

What the v0.6 review identified¶

Three layers were already emerging implicitly across the specifications:

These three layers are correct. What was missing was their formal declaration, which would:

1. Prevent cardinality violations in future catalog entries
2. Enable machine-enforceable composition checks in the validator
3. Give catalog authors a decision tree for where to place a rule
4. Establish the semantic foundation needed before a query engine or UX projection layer can be built

Decision¶

Create specifications/015-semantic-model/ as a new normative module containing four documents:

Key Decisions Within This Specification¶

1. Cardinality is a property of the verb, not the instance¶

An individual catalog author cannot declare contains with 1:1 cardinality. contains always implies 1:N. This is normative.

This prevents a class of subtle modeling errors where authors use contains for singular relationships that should be owns or references.

2. Composition is classification-driven¶

Whether BO A may relate to BO B through verb V depends on the classifications of A and B — not on the author's judgment.

Specifically: - Only aggregate-root may use contains and owns as source - value-object may never be a source for structural or operational verbs - Maximum composition depth: 3 levels from an aggregate-root

3. Three dependency types, not two¶

The industry commonly distinguishes "structural" from "reference" dependencies. UC-BoK declares a third:

• Structural — lifecycle coupled (contains, owns, fulfills, settles)
• Behavioral — process-activated, no lifecycle coupling (uses, applies-to, creates, results-in, allocates, reserves, issues, derives-from, supports)
• Temporal / Contextual — referential only (references, belongs-to, appears-on, located-at)

This distinction has direct implications for event propagation design. Structural dependencies propagate state change events downward. Behavioral dependencies activate only in process context. Temporal dependencies do not propagate.

4. Constraints and Validation Rules are formally separated¶

The authoritative decision rule for authors:

If the rule is always true, regardless of any running process → constraints.yaml
If the rule must be true before or after a specific operation → validation-rules.yaml

This is now normative, not advisory. Future validators will enforce placement.

What This ADR Does NOT Decide¶

• KPI vocabulary: KPI relationships (measured-by) are noted in 006-relationship-model.md as "when modeled". The semantic model does not yet formalize KPI cardinality.
• UX Semantic Model: The Experience Projection layer (Task, Interaction, Screen) is deferred to a future EXP-series specification.
• Cross-specification relationships: How the BO-level semantic model relates to the meta-level relationship model (006-relationship-model.md) is noted but not fully formalized. A future SPEC may consolidate both.

Consequences¶

Positive¶

• Catalog authors have a complete grammar reference — vocabulary + cardinality + composition + dependency
• Machine-enforceable cardinality rules can now be added to the BO schema validator
• The constraint/rule distinction is normative — audit of existing catalogs is now possible
• The semantic foundation is in place for a query engine or UX projection layer
• The three dependency types provide a principled basis for event-driven design patterns

Negative¶

• Existing catalog entries should be audited against the new cardinality rules (particularly contains source classification enforcement)
• The depth limit (3 levels from AR) may surface violations in complex catalog entries
• Authors must now learn the decision tree before placing a rule

Neutral¶

• No existing files are modified by this ADR — it extends the specification set
• No make targets are affected
• The constraint/rule split already exists; this ADR makes it normative, not structural

Implementation¶

1. ✅ Create specifications/015-semantic-model/README.md
2. ✅ Create specifications/015-semantic-model/cardinality.md
3. ✅ Create specifications/015-semantic-model/composition-rules.md
4. ✅ Create specifications/015-semantic-model/dependency-taxonomy.md
5. ✅ Create specifications/015-semantic-model/constraint-vs-rule.md
6. ⬜ Update specifications/007-ontology/relationships.md to reference SPEC-015 for cardinality
7. ⬜ Add cardinality enforcement to scripts/validate_ontology.py (future task)
8. ⬜ Audit existing catalogs/business-objects/*.yaml against composition rules (future task)

Design Principles Established¶

The vocabulary names the verbs. The grammar governs their use.

Inverses are derived, never stored.

Constraints are domain truth. Rules are process guards.

Composition is a property of classification, not author choice.