Create the data-model.md artifact for an OpenSpec change.
This document captures agreements about persistent data: entities, relationships, schema changes, storage patterns, migrations, and invariants. It is created after design and before tasks.
Input: Change name (kebab-case). If omitted, infer from conversation or list active changes.
Steps
Select the change
- Use provided name, or infer from context
- If ambiguous:
openspec list --json and ask the user
Verify prerequisites
openspec status --change "<name>" --json
design and specs MUST be done before creating data-model- If not ready, stop and suggest completing dependencies first
Gather context
- Read
proposal.md, design.md, and delta specs under specs/
- Inspect existing schema when changes touch this repo:
database/migrations/app/Models/- service-specific migration folders if the change spans microservices
- Read main specs in
openspec/specs/ when the change modifies existing capabilities
Get artifact instructions
openspec instructions data-model --change "<name>" --json
Use template, instruction, resolvedOutputPath, context, and rules from the output.
Write data-model.md
- Follow the template structure exactly
- Full document when persistent data changes (tables, columns, FKs, enums, migrations, storage strategy)
- Minimal document when no DB changes: Scope = "No data model changes" + brief reason
- Be concrete: table/column names, types, indexes, FK targets, enum literals
- Align with project conventions (Laravel migrations, Eloquent models, Spatie permission tables, etc.)
- Do not duplicate design rationale — focus on data structure and storage agreements
Validate
openspec status --change "<name>"
openspec schema validate spec-driven
Output
Summarize:
- Change name and path to
data-model.md
- Whether full or minimal (no DB changes)
- Key entities/schema changes (if any)
- Next step: create
tasks.md (via /opsx:propose continuation or manually) — tasks MUST reference data-model decisions
Guardrails
- Never skip
data-model.md — even UI-only changes get a minimal Scope section
- Status literals stored in DB must match spec terminology (with Russian expansions in prose when documenting order/import statuses)
- Cross-service changes: document which service owns each table and how IDs map
- Migration tasks belong in
tasks.md, but schema agreements belong here first
- If design and data model conflict, pause and suggest updating
design.md
1---2name: openspec-data-model3description: Create or update the data-model.md artifact for an OpenSpec change — DB structure, relationships, migrations, and storage conventions. Use when planning persistent data changes, after design and before tasks, or when the user mentions data model, schema, migrations, or database structure in an OpenSpec change.4license: MIT5---67Create the **data-model.md** artifact for an OpenSpec change.89This document captures agreements about persistent data: entities, relationships, schema changes, storage patterns, migrations, and invariants. It is created **after design** and **before tasks**.1011---1213**Input**: Change name (kebab-case). If omitted, infer from conversation or list active changes.1415**Steps**16171. **Select the change**18 - Use provided name, or infer from context19 - If ambiguous: `openspec list --json` and ask the user20212. **Verify prerequisites**22 ```bash23 openspec status --change "<name>" --json24 ```25 - `design` and `specs` MUST be `done` before creating `data-model`26 - If not ready, stop and suggest completing dependencies first27283. **Gather context**29 - Read `proposal.md`, `design.md`, and delta specs under `specs/`30 - Inspect existing schema when changes touch this repo:31 - `database/migrations/`32 - `app/Models/`33 - service-specific migration folders if the change spans microservices34 - Read main specs in `openspec/specs/` when the change modifies existing capabilities35364. **Get artifact instructions**37 ```bash38 openspec instructions data-model --change "<name>" --json39 ```40 Use `template`, `instruction`, `resolvedOutputPath`, `context`, and `rules` from the output.41425. **Write data-model.md**43 - Follow the template structure exactly44 - **Full document** when persistent data changes (tables, columns, FKs, enums, migrations, storage strategy)45 - **Minimal document** when no DB changes: Scope = "No data model changes" + brief reason46 - Be concrete: table/column names, types, indexes, FK targets, enum literals47 - Align with project conventions (Laravel migrations, Eloquent models, Spatie permission tables, etc.)48 - Do not duplicate design rationale — focus on data structure and storage agreements49506. **Validate**51 ```bash52 openspec status --change "<name>"53 openspec schema validate spec-driven54 ```5556**Output**5758Summarize:59- Change name and path to `data-model.md`60- Whether full or minimal (no DB changes)61- Key entities/schema changes (if any)62- Next step: create `tasks.md` (via `/opsx:propose` continuation or manually) — tasks MUST reference data-model decisions6364**Guardrails**6566- Never skip `data-model.md` — even UI-only changes get a minimal Scope section67- Status literals stored in DB must match spec terminology (with Russian expansions in prose when documenting order/import statuses)68- Cross-service changes: document which service owns each table and how IDs map69- Migration tasks belong in `tasks.md`, but schema agreements belong here first70- If design and data model conflict, pause and suggest updating `design.md`
vari-arti