initiative/specs/007-json-import-export/data-model.md

Data Model: JSON Import/Export

Feature: 007-json-import-export Date: 2026-03-27

Entities

ExportBundle

The top-level structure written to and read from .json files. Contains all exportable application state.

Field	Type	Required	Description
version	number	Yes	Format version (starts at 1)
exportedAt	string (ISO 8601)	Yes	Timestamp of when the export was created
encounter	Encounter	Yes	Current encounter state (combatants + turn info)
undoStack	Encounter[]	Yes	Undo history (encounter snapshots, max 50)
redoStack	Encounter[]	Yes	Redo history (encounter snapshots)
playerCharacters	PlayerCharacter[]	Yes	Player character templates

Encounter (existing)

Defined in packages/domain/src/types.ts. No changes needed — exported as-is via JSON serialization.

Field	Type	Required	Description
combatants	Combatant[]	Yes	Ordered list of combatants
activeIndex	number	Yes	Index of current turn (0-based)
roundNumber	number	Yes	Current round (starts at 1)

Combatant (existing)

Defined in packages/domain/src/types.ts. No changes needed.

Field	Type	Required	Description
id	CombatantId	Yes	Unique identifier ("c-N")
name	string	Yes	Display name
initiative	number	No	Initiative roll result
maxHp	number	No	Maximum hit points (>= 1)
currentHp	number	No	Current HP (0 to maxHp)
tempHp	number	No	Temporary hit points
ac	number	No	Armor class (>= 0)
conditions	ConditionId[]	No	Active status conditions
isConcentrating	boolean	No	Concentration flag
creatureId	CreatureId	No	Link to bestiary creature
color	string	No	Visual color (from player char)
icon	string	No	Visual icon (from player char)
playerCharacterId	PlayerCharacterId	No	Link to player character template

PlayerCharacter (existing)

Defined in packages/domain/src/player-character-types.ts. No changes needed.

Field	Type	Required	Description
id	PlayerCharacterId	Yes	Unique identifier ("pc-N")
name	string	Yes	Character name
ac	number	Yes	Armor class (>= 0)
maxHp	number	Yes	Maximum hit points (>= 1)
color	PlayerColor	No	Visual color (10 options)
icon	PlayerIcon	No	Visual icon (15 options)

Validation Rules

Import Validation

1. Top-level structure: Must be a JSON object with version, encounter, undoStack, redoStack, and playerCharacters fields.
2. Version check: version must be a number. Unknown versions are rejected.
3. Encounter validation: Delegated to existing rehydrateEncounter() — validates combatant structure, HP ranges, condition IDs, player colors/icons.
4. Undo/redo stack validation: Each entry in both stacks is validated via rehydrateEncounter(). Invalid entries are silently dropped.
5. Player character validation: Delegated to existing player character rehydration — validates types, ranges, color/icon enums.
6. Graceful degradation: Invalid optional fields on combatants/characters are stripped (not rejected). Only structurally malformed data (missing required fields, wrong types) causes full rejection.

State Transitions

Export Flow

User triggers export
  → Read encounter from EncounterContext
  → Read undoRedoState from EncounterContext
  → Read playerCharacters from PlayerCharactersContext
  → Assemble ExportBundle { version: 1, exportedAt, encounter, undoStack, redoStack, playerCharacters }
  → Serialize to JSON
  → Trigger browser file download

Import Flow

User selects file
  → Read file as text
  → Parse JSON (reject on parse failure)
  → Validate top-level structure (reject on missing fields)
  → Validate encounter via rehydrateEncounter() (reject on null)
  → Validate undo/redo stacks via rehydrateEncounter() per entry (filter invalid)
  → Validate player characters via rehydration (filter invalid)
  → If current encounter is non-empty: show confirmation dialog
  → On confirm: replace encounter, undo/redo, and player characters in state
  → State changes trigger existing useEffect auto-saves to localStorage