Skip to content

ADR-004 — Ontology Modularization

Status: Accepted

Date: 2026-07-04

Proposed by: Architecture Board

Supersedes: ADR-004 (Proposed — Ontology Module, rejected)

Context

UC-BoK now has a normative ontology layer defined in specifications/007-ontology.md.

This single file covers Business Object ontology, Aggregate Root semantics, Entity semantics, Value Object semantics, Lifecycle, Identity, Invariants, Referenceability, Relationships, Graph eligibility, and Catalog authoring rules.

As the ontology expands to cover Events, Processes, Capabilities and APIs, this file will grow into an unmaintainable monolith.

A previous proposal (rejected) suggested creating a new top-level ontology/ directory.

That proposal was rejected because:

  • ontology/ has the same architectural responsibility as specifications/.
  • Introducing it would create two top-level directories with identical roles, breaking ADR-002 Source of Truth Strategy.
  • A top-level directory must represent an architectural responsibility, not a knowledge domain.

The correct solution is to modularize the ontology inside specifications/, following the same pattern as catalogs/business-objects/.

Decision

Replace specifications/007-ontology.md with specifications/007-ontology/, a directory of focused single-responsibility documents.

The specifications/ directory continues to be the single normative location. The ontology becomes a module within it, not a peer of it.

Structure

specifications/007-ontology/
  README.md               — module index, scope, foundational principles
  business-object.md      — Business Object ontology and catalog authoring rules
  aggregate-root.md       — Aggregate Root semantics
  entity.md               — Entity semantics
  value-object.md         — Value Object semantics
  identity.md             — Identity and Canonical Identity
  lifecycle.md            — Lifecycle semantics
  invariants.md           — Invariant semantics
  referenceability.md     — Referenceability rules and graph eligibility

Future additions (not in scope of this ADR):

specifications/007-ontology/
  event.md
  process.md
  capability.md
  service.md
  relationship.md

Governing Principle

This decision is governed by the Top-Level Directory Rule defined in ADR-001:

A top-level directory represents an architectural responsibility. It must never represent a domain of knowledge. Knowledge domains are organized inside their architectural layer.

Consequences

Positive

  • specifications/ remains the single normative location — ADR-002 intact.
  • Each ontology concept is independently referenceable and evolvable.
  • Scales without top-level proliferation.
  • Consistent with the catalogs/business-objects/ precedent.

Negative

  • Requires migrating specifications/007-ontology.md.
  • Requires updating references in schemas/README.md and .context/.

Neutral

  • specifications/ retains all other specification documents unchanged.
  • No make targets or scripts are affected.

Implementation

  1. Create specifications/007-ontology/ directory.
  2. Split specifications/007-ontology.md into per-concept documents.
  3. Add specifications/007-ontology/README.md as module index.
  4. Update schemas/README.md reference.
  5. Update .context/current/ references.
  6. Remove specifications/007-ontology.md.
  7. Run make check to confirm nothing is broken.
  8. Atomic commit.

ONT-004 (Semantic Constraints) and ONT-005 (Relationship Semantics) target specifications/007-ontology/ as their home.