Skip to content

ADR-005 — YAML as Canonical Source Layer

Status

Accepted

Context

UC-BoK stores structured retail knowledge across multiple entity types: capabilities, services, business objects, domains, processes, events, APIs, and applications. A format must be chosen for this source layer that satisfies:

  • human readability (edited by domain experts, not only engineers)
  • machine parseability (consumed by validators, generators, and the knowledge graph)
  • version control friendliness (line-level diffs in git)
  • schema enforceability (JSON Schema Draft-07 can validate YAML via PyYAML + jsonschema)

Alternatives considered: JSON, TOML, relational database, XML, spreadsheets.

Decision

YAML files under catalogs/ are the canonical source layer for all UC-BoK modelled content.

Rules established in SPEC-005:

  1. All catalog YAML files use the same top-level key structure: a list of entities under a plural key matching the entity type (e.g. capabilities:, processes:, events:).
  2. Every entity must have a stable id field in kebab-case.
  3. YAML files must be valid under their corresponding JSON Schema before merge.
  4. YAML is the input to all generators, validators, and graph builders — never the output.
  5. Generated documentation (under docs/generated/) must not be edited directly.

Consequences

  • All retail knowledge changes are made in catalogs/ YAML files, not in Markdown.
  • Markdown documentation is always regenerated from YAML — it is not the source of truth.
  • Any change to catalog structure requires a schema update and a generator update.
  • The site/ directory is purely build output and is never edited.