The Specy domain metamodel defines the vocabulary you use to describe how a system realizes its obligations. It is organized in six layers: an Organization that roots the model, a Decomposition & Exposition layer that breaks the domain into bounded contexts and surfaces their behavior through interfaces, a Structures layer for the concepts that carry identity and value, a Behaviors layer for messages, state machines, and services, a Properties layer for rules and coordination, and a Traceability & Verifiability layer that connects model elements back to requirements and confirms they hold at runtime.

The diagram below maps every concept and its relationships in one place; each entry in the glossary underneath gives a one-sentence definition and a link to the detailed page.

The full, authoritative specification is DOMAIN-METAMODEL.md in the specy-ai/skills repository.

Organization

Organization is the top boundary and wrapper of the work — the named scope of what is being modeled, whether that is a product, a business unit, or a company. It holds one or more bounded contexts and anchors cross-cutting concerns — requirement provenance, context-map topology, and shared vocabulary governance. It carries no behavior of its own; its job is to make the frame of the engagement explicit before anything else is said. See Organization.

Decomposition & Exposition

This layer answers two related questions: how do you break the domain into tractable pieces (decomposition), and how do those pieces surface their capabilities outward (exposition).

Bounded Context — defines one or several domain models with a shared, mutually consistent language and expresses the relations between those models. Interactions across contexts are asynchronous; transactions cannot span them. See Bounded Context.

Module — a unit of decomposition that groups related domain concepts behind a controlled interface; prefer modules over new bounded contexts for pure decomposition of concerns. See Bounded Contexts & Modules.

Context Map Pattern — one of eight integration patterns that govern how two bounded contexts relate: Open Host Service, Customer/Supplier, Conformist, Anti-Corruption Layer, Shared Kernel, Published Language, Partnership, or Separate Ways. See Bounded Contexts & Modules.

Interface — a named surface that exposes a curated subset of operations from entities or domain services to the outside of a module or context. See Interfaces & Operations.

Operation — a named unit of behavior owned by an entity or a domain service; safe or unsafe, idempotent or not, with typed arguments, a return type, preconditions, postconditions, and zero or more emitted events. See Interfaces & Operations.

Structures

This layer describes the concepts with identity or value — the nouns that carry state and compose into the domain’s data model.

Entity — a domain concept with a stable identity and a lifecycle; two entities are equal only if their identities match. See Structures.

Read-only Entity (Master Data) — an entity whose state is owned by another bounded context or external system; observable here, but never mutable. Common examples: Customer, Supplier, Product. Kept in sync via a synchronous lookup or an asynchronous projection. See Structures.

Aggregate — a cluster of entities behind a single root that enforces integrity; all mutations pass through the root and all invariants are evaluated there. See Structures.

Value Type — an immutable concept defined entirely by its attributes; two values are equal if their attributes are equal. Values compose and may be embedded in entities. See Structures.

Enum (Referential) — a closed, named set of values used to constrain a field. Values may be primitive labels (Severity, PaymentMethodType) or instances of a value type (Currencies referencing Currency). When the values are value-type instances, the value type declares a code field that serves as the unambiguous reference. See Structures.

Field, Identifier, Relationship — the building blocks of entity structure: typed fields, the identity attribute, and typed links to other entities. See Structures.

Behaviors

This layer describes everything that moves: the messages entities exchange, the lifecycle transitions they undergo, and the services that orchestrate work across them.

Command — an inbound message expressing the intention to change state; triggers an entity operation and produces at least one success or error event. See Commands, Queries & Events.

Query — a safe, idempotent inbound message that reads current state without side effects. See Commands, Queries & Events.

Event — an append-only recorded fact about something that happened; carries the correlation id of its cause. Events come in four flavors: Internal (raised synchronously from a state transition), External (consumed asynchronously from an upstream context), Error (a failure from an operation), and Temporal (anchored to a time reference, suppressible via a guard). See Commands, Queries & Events.

State Machine — structures an entity’s lifecycle through an explicit set of states and transitions, with one start state and zero or more final states. See Structures.

State — a discrete lifecycle position of an entity; carries state-scoped invariants that must hold while the entity occupies it. See Structures.

Transition — the movement between two states; triggered by an entity operation, guarded by a precondition, validated by a postcondition. See Structures.

Reaction — a reactive rule triggered by an internal, error, or temporal event; evaluates a guard and issues a command. Asynchronous and cross-aggregate. See Reactions.

Domain Service — a stateless operation holder that spans multiple entities or aggregates when ownership by any single one would be arbitrary. See Services.

Application Service — an orchestrator that interprets presentation-layer requests and delegates to the domain; holds use-case state but no domain logic. See Services.

Infrastructure Service — an adapter that exposes an external system’s capabilities through the ubiquitous language; called by domain objects, never the reverse. The Anti-Corruption Layer is implemented as an infrastructure service. See Services.

Properties

This layer collects everything verifiable about the model — every claim a property-based test can target. It includes state predicates, the contracts on operations, the constraints on entity lifecycles, and the cross-aggregate enforcement mechanisms that maintain agreements at runtime.

Invariant — a boolean predicate over state that must hold at every observable point within an aggregate or state; enforced by rejection, compensation, or alert. See Properties.

Agreement — a cross-aggregate truth that no single transaction can verify; bilateral or multilateral; accepts a documented inconsistency window. See Properties.

Precondition & Postcondition — the predicates attached to an operation that gate it on entry and validate its state transition on exit. The full operation contract. See Properties for the verifiability lens; canonical definitions on Interfaces & Operations.

State-machine constraints — guards, transition postconditions, state-scoped invariants, and reachability claims that govern how an entity moves through its lifecycle. See Properties for the verifiability lens; canonical definitions on Structures.

Reconciliation — the mechanism that detects agreement violations and issues compensating commands (choreographed or orchestrated). See Properties.

Escalation Chain — the ordered fallback sequence when reconciliation compensation fails; terminates in alert, suspend, or manual intervention — never in an infinite retry. See Properties.

Traceability & Verifiability

Every domain element carries a satisfies [REQ-…] list that links it back to the system requirements it realizes, and a requirements-source pointer to the originating .sysreq file. These two attributes make the provenance chain file-resolvable from model to obligation in both directions.

Requirement Traceability — covers coverage queries (which must requirements have no satisfying domain element?) and impact analysis (which elements must be revised if a requirement changes?). See Requirement Traceability.

Verifiability — covers how domain elements express what they verify and how those verifications run automatically against a running system. See Verifiability.