Source Model Governance¶

Purpose¶

This document defines how UC-BoK source models are managed, versioned, and validated. All catalog content is expressed as YAML and resides under catalogs/. Markdown documents under docs/ are the publication layer — generated from or informed by the catalog.

Catalog Structure (v1.2.0-alpha)¶

Catalog	Path	Content
Domains	`catalogs/domains.yaml`	8 bounded domains
Capabilities	`catalogs/capabilities.yaml`	25 capabilities (classified)
Services	`catalogs/services.yaml`	60+ business services
Events	`catalogs/events.yaml`	107 domain events
Processes	`catalogs/processes.yaml`	15 end-to-end processes
Applications	`catalogs/applications.yaml`	13 application archetypes
Business Objects	`catalogs/business-objects/*.yaml`	46 BOs (one file each)
Patterns	`catalogs/patterns.yaml`	7 commerce patterns
Reference Architectures	`catalogs/reference-architectures/*.yaml`	3 (Fashion, Grocery, Specialty)
Experience	`catalogs/experience/*.yaml`	actors, interactions, journeys, tasks
Assessment Profiles	`catalogs/assessment-profiles/*.yaml`	UCMI assessment profiles
Vendor Mapping	`catalogs/vendor-mapping.yaml`	Empty — requires SI-led workshop (ADR-017)

Legacy

catalogs/legacy/ contains the original monolithic ucbok.yaml from v0.1. It is read-only and will be removed after full migration is complete.

Governance Rules¶

Rule 1 — Model First¶

New UC-BoK concepts SHALL be added to the appropriate YAML catalog before any Markdown documentation is written.

Rule 2 — Ontology Before Catalog¶

Each concept type requires a normative ontology specification before catalog entries are accepted:

Concept	Ontology Spec
Business Object	`specifications/007-ontology/`
Capability	`specifications/008-capability-ontology/`
Event	`specifications/009-event-ontology/`
Process	`specifications/010-process-ontology/`
Application	`specifications/011-application-ontology/`

Rule 3 — Stable Identifiers¶

Every model element SHALL have a stable lowercase kebab-case id.

id: order          # Business Object
id: bopis          # Process
id: oms            # Application
id: order-placed   # Event

Rule 4 — Cross-Reference by ID¶

Cross-references between catalogs SHALL use stable id values, not display names.

# ✅ Correct
source-capability: order-management

# ❌ Wrong
source-capability: Order Management

Rule 5 — Classification Required¶

All catalog entries SHALL carry a classification field aligned with the ontology spec for that concept type.

Rule 6 — Traceability¶

Every process SHALL be traceable to:

capabilities — UC-BoK capabilities involved
domains — domain boundary coverage
applications — application archetypes required
trigger / trigger-event — what initiates the process
outcome — measurable business result

Validation Pipeline¶

All rules above are enforced by automated validators wired into make check:

make validate               → YAML reference integrity
make validate-ontology      → 39 Business Objects
make validate-capabilities  → 22 Capabilities
make validate-events        → 73 Events
make validate-processes     → 12 Processes
make validate-applications  → 12 Applications

Run make check before every commit.

Markdown as Publication Layer¶

YAML Catalog  →  Generator Script  →  docs/generated/
                                       ↓
                                   MkDocs site

Pages under docs/generated/ are never edited manually. Run make generate to regenerate them from catalogs.

References¶

specifications/ — normative ontology and architecture specifications
ADR-001 — Canonical Repository Layout
ADR-002 — Ontology Modularization