Writing a design

This is the complete reference for the design document. The JSON Schemas in schema/ are its machine-readable form; where the two disagree, one of them is a bug and neither is changed silently.

Conventions

These hold in every Zeema document, not just designs.

• Quote every string value, including enum values and schemaVersion. Unquoted NO, yes, on and 1.0 parse as booleans or numbers in YAML, and will not mean what you typed.
• Property names are camelCase. Ids and enum values are kebab-case.
• No display text in any document except locales/. Names are looked up by id.
• The first line points at the schema, so an editor validates the file with no other setup.

The envelope

Every design starts with the same three fields.

1# yaml-language-server: $schema=https://zeema.dev/schema/design.schema.json
2schemaVersion: "1"
3type: "design"
4id: "order-processing"

Then, in this order and all optional except nodes and edges: requirements, groups, nodes, edges.

requirements

What the whole design promises about itself. Rules compare nodes against these. Every path is optional, and an absent requirement never equals anything — a design that promises nothing is never judged against a promise it did not make.

1requirements:
2  availability: { multiRegion: true, sla: "99.95" }
3  messaging:    { replay: true }
4  latency:      { p95Ms: 300 }

groups

Nested boundaries. A node belongs to at most one group; a group may have one parent.

1groups:
2  - { id: "eu-west-1", kind: "region" }
3  - { id: "prod-vpc", kind: "vpc", parent: "eu-west-1" }
4  - { id: "dmz", kind: "trust-zone", parent: "prod-vpc" }

Groups carry no properties in v1 beyond label and count. They exist for rules — inGroup, crossesGroup — and for renderers, which draw them as nested boxes.

nodes

1nodes:
2  - { id: "api", component: "aws-api-gateway" }
3  - id: "orders-queue"
4    component: "sqs"
5    label: "Orders queue"
6    group: "prod-vpc"
7    props: { deadLetterQueue: true, retentionDays: 14 }
8    nfr:   { rps: 500, latencyP95Ms: 40, consistency: "strong" }

Modules inside a node

A service deployed as one unit can still say what it is made of. List its modules, and point an edge at one as <nodeId>/<moduleId>:

1nodes:
2  - id: backend
3    component: container-service
4    modules:
5      - { id: api, label: "API" }
6      - { id: otp, label: "OTP" }
7edges:
8  - { from: backend/otp, to: sms, mode: sync, protocol: https }
9  - { from: backend/api, to: backend/otp }

Rules read a module end as its node, so backend/otp calling sms counts exactly as backend calling it. An edge with both ends inside one node is in-process: it is not a network hop, takes no mode or protocol, and rules ignore it. The box is drawn collapsed with an "N modules" chip.

Property resolution order

The effective value of a property on a node is the first of these that exists:

1. The node's props
2. The component's defaults
3. The property definition's default — on the kind, or on the component for a component-specific property
4. Absent

A node may only set properties that exist on its component's kind or on the component itself. Anything else is a structural error, not a warning.

edges

Directed. from and to are node ids in this design, or a group id for an edge to the group as a unit, drawn once to its frame. Rules read a group end as every node inside the group, nested groups included, as if the edge had been drawn to each: hasEdge on a member counts it, and an edge rule fires on the group edge (once) when any member pair would trip it.

1edges:
2  - { from: "api", to: "orders-queue", protocol: "https", mode: "async", delivery: "at-least-once" }
3  - from: "checkout-service"
4    to: "psp"
5    protocol: "https"
6    mode: "sync"
7    timeoutMs: 2000
8    retryPolicy: "exponential-jitter"
9    idempotent: true
10    circuitBreaker: true
11    fallback: "degraded"

Those seven optional fields are the only edge properties in v1, and each exists because a real rule reads it. Anything else about an edge goes in label.

auth says how the caller authenticates on that hop. A managed identity, an IAM role or a service account is not a box between every caller and callee; it is how the edge authenticates:

1edges:
2  - { from: "orders-api", to: "orders-db", protocol: "tds", mode: "sync", auth: "managed-identity" }

The canvas and the SVG export draw it as a small glyph on the line by the source end: the cloud's own mark for managed-identity (Azure managed identity), iam-role (AWS IAM) and service-account (Google Cloud IAM), a shield for workload-identity, a key for api-key and basic, a lock for mtls and oauth, nothing for none. Any other value is a structural error.

What makes a document structurally valid

These are checked before any rule runs, and every one of them blocks a save. The wording below is the wording the linter uses.

On top of that, the document is checked against schema/design.schema.json: unknown fields, missing required fields and wrong types are reported with the path that carried them.

A complete design

Everything above, in one file.

1schemaVersion: "1"
2type: "design"
3id: "checkout"
4
5requirements:
6  availability: { multiRegion: false }
7  messaging: { replay: false }
8  correctness: { exactlyOnceEffect: true }
9
10groups:
11  - { id: "eu-west-1", kind: "region" }
12  - { id: "prod-vpc", kind: "vpc", parent: "eu-west-1" }
13  - { id: "dmz", kind: "trust-zone", parent: "prod-vpc" }
14
15nodes:
16  - id: "web-client"
17    component: "web-browser"
18    props: { platform: "web" }
19
20  - id: "api"
21    component: "aws-api-gateway"
22    group: "dmz"
23    props: { idempotencyKeys: true }
24    nfr: { rps: 300 }
25
26  - id: "checkout-service"
27    component: "container-service"
28    group: "prod-vpc"
29
30  - id: "orders-queue"
31    component: "sqs"
32    group: "prod-vpc"
33    props: { deadLetterQueue: true, retentionDays: 14 }
34
35  - id: "orders-db"
36    component: "postgres"
37    group: "prod-vpc"
38    props: { backupEnabled: true, backupRetentionDays: 30, encryptionAtRest: true }
39
40edges:
41  - { from: "web-client", to: "api", protocol: "https", mode: "sync", timeoutMs: 3000 }
42  - { from: "api", to: "checkout-service", protocol: "http", mode: "sync", timeoutMs: 2000 }
43  - { from: "checkout-service", to: "orders-db", protocol: "postgres", mode: "sync" }
44  - { from: "checkout-service", to: "orders-queue", protocol: "https", mode: "async", delivery: "at-least-once" }

What v1 deliberately does not have

• Kind-to-kind inheritance
• Object or list property types
• Properties on groups, or on edges beyond the six optional fields above
• Expressions in rules
• Layout hints of any sort
• Any reference to a file outside the repository

Each is a candidate for v2 once a real design proves it necessary, and the evidence is recorded rather than argued.