# Openspec Data Model

> 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.

- Skill: `vari-arti/openspec-data-model` (Agent Skill)
- Install (CLI): `npx skillmds@latest add vari-arti/openspec-data-model`
- Raw SKILL.md: https://api.skillmd.com/api/skills/vari-arti/openspec-data-model/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: MIT
- Author: vari-arti (https://skillmd.com/u/vari-arti)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/vari-arti/openspec-data-model

---


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**

1. **Select the change**
   - Use provided name, or infer from context
   - If ambiguous: `openspec list --json` and ask the user

2. **Verify prerequisites**
   ```bash
   openspec status --change "<name>" --json
   ```
   - `design` and `specs` MUST be `done` before creating `data-model`
   - If not ready, stop and suggest completing dependencies first

3. **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

4. **Get artifact instructions**
   ```bash
   openspec instructions data-model --change "<name>" --json
   ```
   Use `template`, `instruction`, `resolvedOutputPath`, `context`, and `rules` from the output.

5. **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

6. **Validate**
   ```bash
   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`