Skip to main content
Every Conseqa model is a single YAML file whose root object is a Model. The file declares one logical architecture snapshot — a revision-stamped collection of services, schemas, data objects, topics, state machines, and operations. Validation checks that all references are coherent; verification checks whether the requirements declared inside operations follow from the declared facts and architecture.

Top-level fields

integer
required
An opaque numeric revision marker for the model. Conseqa assigns no ordering, compatibility, or migration semantics beyond numeric identity — it is a label you control.
map[Id → Service]
required
A map of service declarations. Each service is a logical ownership boundary that groups related operations. See Service kinds below.
map[Id → Schema]
required
A map of schema declarations — both canonical shapes and fragment projections. Schemas describe the logical type of every payload, field, and data object in the model. See Field Types.
map[Id → DataModel]
required
A map of data model declarations. A data model is a logical transactional state boundary containing persistent object classes. Required even when empty (data_models: {}).
map[Id → Topic]
required
A map of topic declarations. Topics carry messages between producers and consumers and declare ordering and identity guarantees.
map[Id → StateMachine]
required
A map of state machine declarations. A state machine governs the lifecycle of a data object by declaring valid states, transitions, and per-transition side effects. Required even when empty (state_machines: {}).
map[Id → Operation]
required
A map of operation declarations. Each operation belongs to one service and declares inputs, effects, transactions, a program, and requirements to verify. Required even when empty (operations: {}).

Services

A service groups related operations under a logical ownership boundary. It carries a kind that classifies its role in the architecture.
string
required
One of backend, frontend, worker, or job. These are descriptive labels only — a kind does not itself imply a process boundary, network hop, replica count, or failure-independence model.

Annotated skeleton

The following skeleton shows every top-level key and its relationship to the rest of the model. Each section links to the relevant reference page.

ID conventions

Every key in the maps above is a logical Id — a string you choose. Conseqa treats IDs as opaque logical names, not runtime addresses, database keys, or deployment identifiers. The namespaced dot-separated style (service.checkout, schema.CreateOrderRequest) used throughout the fixtures is a convention, not a requirement.
IDs must be unique within their map. A schema named string, bool, int, float, decimal, uuid, or timestamp conflicts with the scalar type shorthand and must use the canonical field-map form wherever its type is referenced. See Field Types.

What validation and verification check

Validation and verification are two separate passes:
  • Validation (structural) checks that every reference resolves, programs terminate on every path, artifacts are definitely available where consumed, and result bindings are in scope. A structurally valid model may still have unproven requirements.
  • Verification checks whether each declared requirement — serialization, ordering, idempotency, recoverability — follows from the declared facts. Verdicts are proven, unknown, or disproven. An unknown verdict means the verifier could not establish the property, not that it is false.

Field Types

Scalar types, optional fields, list types, and schema definitions

Effects

Publication, request, and external effects

Program Control

Steps, decisions, terminals, and step locations

Value References

ValueRef sources, field paths, and derivation