The YAML format

A Catenator spec is a YAML document. This section covers the fields you need to write a working spec — the header, the system declaration, and the macro/meso/micro hierarchy.

Spec header

The spec header identifies the spec and pins the versions of the standard it was authored against.

spec:
  version: "1.0.0"
  authored: "2026-06-18"
  status: ground-truth
  standard-version: "1.0.0"

Field	Required	Definition
version	required	The version of this spec — incremented on any change
authored	required	The date this version was authored — ISO 8601
status	required	One of: draft, ground-truth, published, deprecated
standard-version	required	The version of the Catenator standard this spec conforms to

System declaration

The system block declares what is being specified. One system block per spec.

system:
  name: restaurant-ordering-system
  display-name: "Table ordering"
  display-name-source: inferred

Field	Required	Definition
name	required	Machine-readable identifier — kebab-case
display-name	required	Human-readable name for any generated output
display-name-source	required	authored — use exactly as written. inferred — agent may refine.

Macros, mesos, micros

A spec contains one or more macros. Each macro contains one or more mesos. Each meso contains one or more micros. A micro is the atomic unit — not further decomposable.

macros:
  - name: ordering
    display-name: "Ordering"
    display-name-source: inferred
    source: "Diners browse a menu and place orders from their table."
    mesos:
      - name: ordering.cart
        display-name: "Order"
        display-name-source: inferred
        micros:
          - name: cart
            display-name: "Order"
            display-name-source: inferred
            descriptor: model
            definition: "The collection of items a diner has selected before submitting."

Field	Required	Definition
name	required	Canonical identifier. Mesos namespaced to macro: macro.meso
display-name	required	Human-readable name
display-name-source	required	authored or inferred
source	optional	The prose fragment justifying this item's inclusion
descriptor	required (micro only)	The Catenator descriptor type
definition	required (micro only)	A precise, single-sentence definition

display-name-source

Value	Meaning
authored	The author specified this name. Output MUST use it exactly.
inferred	A suggested name. The agent may refine based on context.

Descriptor types

The descriptor field on a micro declares which Catenator descriptor the item belongs to.

Value	What it specifies
model	A data structure the system operates on
operation	An individual action the system performs
rule	A constraint the system must enforce
event	Something the system must respond to
process	A workflow the system executes
actor	Who or what interacts with the system
service	A capability the system exposes or consumes
integration	A boundary with an external system
utility	What the system does, for whom, and to what end
risk	What can go wrong, how likely, and who bears it