Domain Model Author

Authoring a domain model

A domain model is the canonical, plain-language expression of what a product is: its named concepts (entities), how they relate, the rules that govern them (invariants), and short narratives that stress-test the whole (scenarios). The YAML is the output of a conversation, not something the user hand-writes. Your job is to run that conversation and produce well-formed YAML.

Before you write anything

1. Check that modelith is installed. Run modelith --version (or command -v modelith). If it is not on PATH, stop and tell the user to install it: go install github.com/stacklok/modelith/cmd/modelith@latest, or download a release binary from https://github.com/stacklok/modelith/releases. Do not hand-write YAML you cannot lint — the linter is what keeps the model valid; without it you are guessing.
2. Read the schema. Run modelith schema — that is the source of truth and works wherever modelith is installed. (Only when you are working inside the modelith repo itself may you instead read internal/schema/v1/modelith.schema.json directly; that path does not exist in a consuming repo.) Every file you produce must validate against it.
3. Read the existing model. Find the relevant *.modelith.yaml in the repo and read it in full, plus its rendered .md if present. New entries must be consistent with existing names and relationships.
4. Read the philosophy if you have not: the modelith docs explain why naming and invariants matter.

Build order — skeleton first

A model isn't built field-by-field down one entity; it's built in passes across the whole model, each pass a coherent layer you could stop at. Going deep on one entity — all its attributes, actions, enums — before the others exist is the fastest way to a lopsided model and an exhausted user. Work breadth-first, in this order:

1. Pass 1 — the skeleton (do this completely first). Name every entity and give each a crisp two-to-four-sentence definition; declare the relationships and cardinality between them. Nothing else yet. This is the highest-leverage work in the whole exercise — naming is the commitment — and it already renders to a real ER diagram. This is the minimum useful model: a skeleton that lints and reads as a coherent artifact is worth circulating before any detail is added. Don't move past Pass 1 until the whole skeleton stands.
2. Pass 2 — the behavior. Add invariants (the rules that must always hold) and scenarios (short narratives that exercise every entity). These need the skeleton first — you can't write a sharp invariant before the nouns and structure are settled. The linter's completeness layer nudges here: it warns about entities with no invariants and entities no scenario touches. Attach an invariant to the entity it governs; if a rule genuinely spans several entities with no single owner, put it in the top-level invariants list instead (see "Writing the YAML").
3. Pass 3 — refinement. Fill in attributes (and derived ones), enums, actions, glossary roles, ownership, and role/note detail — but only where they add clarity. This is a long tail, not a checklist to exhaust. The "defined but never referenced" warnings on glossary and enums exist precisely to stop you front-loading detail that hasn't earned its place.

You can stop after any pass and have something honest. Treat Passes 2 and 3 as enrichment of a model that is already useful, not as the work of "finishing" it.

The conversation

Your value is in the questions, not the typing. The questions track the passes above — settle naming, relationships, and cardinality across the whole model before you probe rules and scenarios. Probe until the model is sharp:

• Naming is a commitment. When the user says "rule" or "config," ask what the concept actually is. The right name (Policy vs Rule vs Constraint) reflects a decision about what it does and what it includes/excludes.
• Fuzziness is a signal. If the user can't give a crisp two-to-four-sentence definition, or isn't sure whether two things are the same concept, that gap is the point. Surface it; don't paper over it.
• Push on invariants. "What must always be true?" is where the real behavior lives. Write them short, declarative, and testable.
• Ownership and cardinality. For each relationship: one-to-one, one-to-many, or many-to-many? And is the related entity part of this one — can it exist on its own? ownership: owned means no: it's a part that can't exist without this entity (composition), so it's deleted along with it. referenced (or omitting ownership) means it's an independent entity this one merely points at. Anchor on "part-of / can't exist independently," not on vaguer notions of control or exclusivity.
• Which side to declare from. A relationship can be declared from either entity, and the linter lets you declare it from both (it checks the two cardinalities are inverses). Prefer declaring it once, from the parent — the entity that owns or contains the other, or sits on the "one" side of a one-to-many (declare Project → Policy, not the reverse). Use the parent's perspective whenever there's an intuitive one; reach for a both-sides declaration only when each view genuinely adds clarity.

Writing the YAML

Follow the format exactly (see the schema reference). Key conventions:

• Top of file: the schema header (copy the exact $id from modelith schema output, or use # yaml-language-server: $schema=https://modelith.sh/schema/domain-model/v1.json), then kind: DomainModel and version: v1.
• Entity keys are canonical PascalCase names (Project, not project).
• Backtick entity names in freeform text — definitions, role, note, invariants, scenario steps: `Project`. In structured fields that already imply an entity (actors, relationship entity:, entity keys), do not backtick.
• cardinality is one of 1:1, 1:n, n:1, n:n. If you declare the same relationship from both entities, the two cardinalities must be inverses (1:n ⇄ n:1; 1:1/n:n symmetric) — a contradiction is a lint error. So is a pair where both ends claim ownership: owned — a relationship is owned by at most one end. The two ends may name different roles; the diagram folds them into one line either way. But if one entity declares two relationships to another and that other declares one back, the pairing is ambiguous (a lint warning) and the diagram draws all three lines. Declaring each relationship from one side only is fine and usually clearer.
• role is a short role name (`Owner`, `Predecessor`), not a sentence: it is the only label drawn on the diagram line, so prose there collides with neighbouring lines and warns. Put the explanation in note. ownership needs no label — it draws as a solid vs dashed line.
• shared: true (top level) marks a model other models are expected to import. It relaxes the "defined but never referenced" completeness checks for this model's own enums and glossary terms — the references that justify them live in files this model can't see — but not the entity-invariant or scenario-coverage checks, which are about gaps in this model itself. Mark a pure-vocabulary model (one that exists to be imported, not used on its own) shared: true so it can pass --completeness error.
• imports (top level) lists other model files this one references, each a path relative to this file: a bare string (./payments.modelith.yaml, whose filename gives the scope — payments) or {scope, path} to name the scope explicitly. Reference an item from an imported model as scope.Name in an attribute type — only there; relationship.entity and subtypeOf cannot be qualified this way (not supported yet, and the linter says so explicitly if you try). An import must resolve inside the repository holding this model (the nearest ancestor directory with a .git entry, or this model's own directory if there is none) and name a readable, supported-version domain model, or it's a lint error. An import nothing references is a completeness warning: drop it, or reference one of its enums.
• glossary (top level) defines non-entity vocabulary — roles like Owner, states, domain nouns — as Term: "definition". Define any role or actor name here; an undefined role warns, and an unused glossary term warns.
• enums (top level) defines enumerated types by PascalCase name, each with values (a list of {name, definition}). An attribute selects one via type: ProjectStatus. Do not write type: "enum[active, archived]" — that is not a valid type; use the PascalCase name of an enum you defined under enums.
• Attribute type is a primitive in lowercase (string, integer, boolean, timestamp), the PascalCase name of a defined enum, or a cross-model reference — scope.Name, naming an enum in a model bound by imports (see above). A PascalCase type that names no enum warns; a scope.Name type whose scope isn't imported, or that names no enum in the model it resolves to, is an error. A dot anywhere in type is reserved for a cross-model reference — decimal(10.2), google.protobuf.Timestamp, and any other dotted string that isn't a well-formed scope.Name is a lint error, not a primitive you can invent; there is no dotted primitive form in this format. Mark computed values with derived: true plus a derivation: (required when derived).
• actions items are either a bare string (create) or a structured object {name, actor?, preserves?, description?}. Use the object form to tie an action to its actor (an entity or glossary term) and the invariant ids it preserves. Mixed bare + structured in one list is fine.
• invariants items are {id, statement}. The id is lowercase kebab-case and unique across the model; statement is the rule (backtick entity names). References point at the id, never the text. Invariants live in one of two places: under the entity they govern (entities.<X>.invariants), or — for a rule that spans several entities with no single owner — in the top-level invariants list (sibling to entities). Both share the same shape and one id namespace. Prefer the entity scope; reach for the top-level list only when no single entity is the rule's home.
• Scenario invariants_touched is a list of invariant ids. Each must reference a declared invariant — a dangling id is a lint error. A reference resolves against both scopes (entity-level and top-level). If a scenario needs an invariant that doesn't exist yet, add it (to the owning entity, or the top-level list if cross-entity) and reference that.

Hard rules the schema enforces (these are errors)

Get these right the first time; they fail modelith lint structurally:

• No unknown keys, anywhere (additionalProperties: false at every level). A misspelled field like definiton: is a hard error, not a silent no-op.
• Required fields: every entity needs a definition; every relationship needs entity + cardinality; every scenario needs name + at least one steps entry; every attribute needs name + type; every invariant needs id + statement; every enum needs at least one values entry; a derived attribute needs a derivation.
• Entity keys and relationship targets are PascalCase, two or more characters, no underscores or hyphens (TargetUser, not target_user).
• cardinality is exactly one of 1:1, 1:n, n:1, n:n; ownership, when present, is exactly owned or referenced.

Avoid these linter false positives

The semantic checks are heuristic; these patterns trip warnings that aren't real bugs, so steer around them:

• Don't backtick a PascalCase word that isn't a defined entity, role, or actor. a `Webhook` fires warns if Webhook is no entity — either define it, name it as an actor/role, or drop the backticks.
• Irregular plurals aren't understood. The linter matches Policy/Policies and Project/Projects (a naive pluralizer), but exotic plurals may not resolve — prefer the singular entity name in backticks.
• invariants_touched and action preserves reference invariant ids, not statements. Use the invariant's id (entity-level or top-level — both resolve); a non-existent id is an error (not a silent miss), so it's safe — but make sure the id actually exists.
• An action actor must be a defined entity or glossary term. actor: admin (lowercase, or any name you haven't declared) warns — define it in the glossary first, or use the entity name.

Always finish by validating and rendering

After any edit:

modelith lint <file>           # resolve errors; explain remaining warnings to the user
modelith render <file>         # regenerate the committed Markdown

Reading exit codes: modelith lint exits non-zero when there are errors (or, with --completeness error, on completeness gaps) — that is the model telling you to fix something, not a tool failure. A usage error is different: an error: line about a missing file or unknown flag is a bad invocation, not a finding. Distinguish the two before reacting, and don't loop on a usage error.

Keep the .yaml and the regenerated .md in sync, and never edit the .md by hand — it is generated. Commit them together when the user is ready; don't commit on your own unless they ask.

Changing vs. adding

• Adding (new entity, attribute, scenario) is low-ceremony: draft, lint, done.
• Changing an existing definition, name, or cardinality is a breaking change that ripples through code, docs, and anything primed on the old meaning (including agents). Call this out explicitly, summarize the blast radius, and make sure the user wants it before proceeding.