ADR-003 — Canonical Knowledge Model¶

Status: Accepted

Date: 2026-07-04

Owner: Architecture Board

Decision Type: Foundational

Context¶

UC-BoK has completed its repository foundation.

The repository now has a frozen source-of-truth strategy:

• PROJECT.md defines project constitution.
• adr/ records architecture decisions.
• specifications/ defines normative rules.
• schemas/ defines machine-readable validation.
• catalogs/ defines canonical knowledge.
• graph/ and queries/ make knowledge executable.

The next foundation is conceptual rather than structural.

UC-BoK must define what its knowledge entities mean before expanding catalog content. Without a canonical knowledge model, catalogs risk becoming lists of terms rather than a coherent ontology.

Decision¶

UC-BoK SHALL use a canonical knowledge model.

The knowledge model defines:

• what can be cataloged
• what can be referenced
• what can become a graph node
• what can become a graph relationship
• which concepts are ontology rules
• which concepts are catalog content

Catalogs SHALL instantiate the knowledge model. They SHALL NOT redefine it.

Knowledge Entity Types¶

Business Object¶

A Business Object is a canonical business concept with identity, lifecycle, ownership and relationships.

A Business Object MAY be classified as:

• aggregate root
• entity
• value object

A Business Object SHOULD define:

• identifier
• name
• description
• classification
• lifecycle
• owner
• attributes
• relationships
• invariants
• events that change or observe it
• processes, capabilities and applications that use it

Business Objects are graph nodes.

Aggregate Root¶

An Aggregate Root is a Business Object that owns a consistency boundary.

It is the authoritative entry point for related entities and value objects.

An Aggregate Root SHALL have:

• stable identity
• lifecycle
• ownership
• invariants
• explicit relationships to contained or referenced objects

Aggregate Roots are graph nodes.

Entity¶

An Entity is a Business Object with stable identity inside a business context.

An Entity MAY be owned by an Aggregate Root or referenced by another Business Object.

Entities are graph nodes when they are independently referenced.

Value Object¶

A Value Object is a Business Object or object component identified by its value rather than by independent lifecycle identity.

Value Objects MAY be cataloged when they are part of the shared language.

Value Objects are graph nodes only when the catalog requires independent referenceability.

Capability¶

A Capability is a stable business ability.

It describes what the enterprise can do, not how a system implements it.

A Capability SHALL:

• belong to a domain
• provide or require business services
• use business objects directly or through services
• be referenceable by processes, applications, vendors and assessments

Capabilities are graph nodes.

Business Service¶

A Business Service is a reusable business operation with a business outcome.

It is not an API endpoint and not an application function.

A Business Service SHALL:

• belong to a domain
• manipulate one or more business objects
• support one or more capabilities
• publish zero or more business events

Business Services are graph nodes.

Business Process¶

A Business Process is an ordered business flow that coordinates domains, capabilities, services, business objects, applications and events.

A Business Process SHALL:

• reference participating domains
• require capabilities or services
• use business objects
• be supported by applications when applicable
• produce or consume events when modeled

Business Processes are graph nodes.

Business Event¶

A Business Event is a named business-significant occurrence.

An Event records that something happened.

An Event SHALL:

• have stable identity
• reference the business object it changes or observes
• be published by a business service or application when modeled

Business Events are graph nodes.

State Change¶

A State Change is a lifecycle transition of a Business Object.

A State Change MAY be represented by a Business Event when the transition is business-significant and needs to be referenced, published, consumed or audited.

Not every State Change is automatically a Business Event.

State Changes are ontology semantics unless explicitly cataloged.

Application¶

An Application is an executable system component or logical application responsibility.

An Application SHALL:

• implement services or capabilities
• support processes when modeled
• publish or consume events when modeled
• own APIs when modeled

Applications are graph nodes.

API¶

An API is a technical exposure of one or more business services.

An API SHALL reference the business service it exposes.

APIs are graph nodes.

Domain¶

A Domain is a coherent business area that owns related concepts.

A Domain SHALL own or group:

• business objects
• capabilities
• business services

Domains are graph nodes.

Vendor Mapping¶

A Vendor Mapping is an external coverage view over the canonical model.

It SHALL NOT define canonical knowledge.

Vendor Mappings may reference capabilities, services, applications and processes.

Vendors are graph nodes.

Assessment¶

An Assessment is an evaluation view over canonical knowledge.

It SHALL NOT define canonical knowledge.

Assessments may reference capabilities, processes, applications or domains.

Assessments MAY be graph nodes when modeled as catalog entities.

Identity Rules¶

Every cataloged knowledge entity SHALL have a stable ID.

IDs are type-scoped unless a schema explicitly requires global uniqueness.

Display names SHALL NOT be used as canonical references.

Aliases MAY be used for lookup and migration, but aliases SHALL NOT replace canonical IDs.

Referenceability Rules¶

An entity may be referenced when it has:

• stable ID
• defined entity type
• source catalog
• lifecycle or status when applicable

The following are always referenceable when cataloged:

• Domain
• Capability
• Business Service
• Business Object
• Business Process
• Business Event
• Application
• API
• Vendor

Attributes and invariants are not independently referenceable unless promoted to cataloged entities by a future ADR.

Relationship Rules¶

Relationships SHALL use the relationship model defined in specifications/006-relationship-model.md.

Catalog-specific relationship labels MAY exist only when scoped to that catalog.

Cross-catalog relationships SHALL use canonical relationship semantics.

Derived relationships SHOULD be generated rather than duplicated manually.

Invariant Rules¶

An invariant is a rule that must remain true for a Business Object or Aggregate Root.

Invariants belong to the ontology layer when they define consistency semantics.

Invariants belong to catalog content when they describe a specific cataloged object.

Invariants SHALL NOT be hidden in documentation prose when they affect validation or graph semantics.

Catalog Content vs Ontology Rule¶

Consequences¶

• Future catalog work should start from Business Object ontology and aggregate boundaries before expanding events, capabilities or processes.
• The graph builder should progressively expose ontology classification.
• Schemas should validate classification, lifecycle, relationships and invariants when those fields are introduced.
• Documentation should explain ontology decisions but must not become their source of truth.