agiledancers/specs/implemented/S1_School-JSON-import-export.md

# S1 — School JSON import and export

Status: implemented

## User story

**As** a school maintainer,
**I want** to export and import my dance school as a JSON file,
**so that** I can store my school configuration locally while the application does
not offer persistent storage,
**and so that** I retain ownership of my data.

## Intent

Export downloads a complete snapshot of one dance school to a local JSON file.
Import restores that snapshot as a new school or replaces the corresponding
existing school after explicit confirmation.

## Scope

### In scope

- Exporting an existing school to a readable JSON file.
- Importing a school that does not exist or no longer exists.
- Replacing an existing school with the complete imported snapshot.
- Preserving all configured school data and relationships, including:
  - School details and its persistent unique key.
  - Dancers and their details.
  - Dance groups, types, age ranges and styles.
  - Dancer memberships, including dancers belonging to multiple groups.
  - Shows, dates, day parts and any existing group assignments to day parts.
  - Coaches and any existing links between coaches and groups.
- Full validation, an import preview, confirmation and clear error messages.

Preserving existing data does not add management screens for coaches or the
ability to assign groups to show day parts.

### Out of scope

- Merging an imported snapshot with an existing school.
- Persistent server-side storage.

The existing-school prompt includes a merge option, but selecting it only displays
that merging is not yet supported. It must not change any data. Implementing merge
behavior requires a separate specification.

## Identity and file format

- Every school has a persistent unique key that is included in exports and
  preserved through imports and subsequent exports.
- Import identifies an existing school by that key, not by its name or a
  runtime-generated numeric ID. The key remains meaningful after a server restart.
- A school with the same name but a different unique key is a separate school.
- A file contains one school and all data needed to restore it without accessing
  another school or the original server state.
- The readable, documented JSON format includes a `formatVersion` field.
- Users may edit the JSON manually. Edited files undergo the same validation as
  files produced by the application.
- Unknown fields and unsupported format versions are rejected explicitly; data
  must not be silently ignored.
- Relationships in the file must be unambiguous and restored correctly. Internal
  numeric IDs need not remain identical, provided school identity and all
  relationships are preserved without collisions with other schools.

## Export flow

1. The maintainer opens an existing school's management screen.
2. The maintainer selects the JSON export option.
3. The application downloads a JSON file containing a consistent, complete
   snapshot of that school.
4. Export does not change the school or any other application data.

## Import flow

1. The maintainer selects the JSON import option and chooses a local file.
2. The application validates the entire file before changing any stored data.
3. For a valid file, the application shows a preview containing the school name
   and the numbers of dancers, dance groups and shows.
4. If the unique school key is unknown, the maintainer confirms adding the school
   or cancels the import.
5. If the key already exists, the application identifies the school that would be
   replaced and offers replace, merge or cancel:
   - **Replace:** explicitly warn that the existing school is replaced completely.
     After confirmation, replace all its configured data with the snapshot.
   - **Merge:** show a message that this functionality is not yet supported and
     leave all data unchanged.
   - **Cancel:** leave all data unchanged.
6. A confirmed import is committed as one operation. The application must not
   expose a partially imported or partially replaced school.
7. If validation or importing fails, show **"Import niet gelukt"** together with
   the concrete cause. The user can correct the file and try again.

## Validation and failure behavior

- Validate JSON syntax, the supported file structure and format version, required
  data, field values and all relationships before applying the import.
- Reject unknown fields and references to missing objects, including a group's
  reference to a dancer absent from the snapshot.
- A failure must not create a partial school, partially replace an existing
  school, or modify another school.
- A replacement must not remove the original school until the complete
  replacement can succeed. If it fails, the original school remains intact.
- Error messages explain the cause specifically enough to correct the file.
  For example: **"Import niet gelukt: groep Hiphop verwijst naar een onbekende
  danser."**

## Acceptance criteria

### Export

1. Each existing school offers a JSON-file export that can be downloaded and
   stored locally.
2. The export includes its persistent unique key, `formatVersion`, all configured
   data listed in scope and all relationships between those objects.
3. Exporting leaves the application data unchanged.
4. A school with no dancers, groups or shows can be exported and imported.

### Adding a school

5. A valid file with an unknown school key shows the preview before any data is
   added. Confirming creates the complete school; cancelling changes nothing.
6. An exported school can be restored after the original school is deleted or
   the in-memory server state is lost.
7. An existing school with the same name but a different key is neither replaced
   nor treated as the same school.

### Replacing a school

8. A valid file with an existing school key prompts the user to replace, merge or
   cancel and clearly identifies the existing school.
9. Confirming replacement replaces the complete configuration. Objects and
   relationships present only in the previous configuration are not retained as
   part of the replaced school.
10. Other schools remain unchanged by replacement.
11. Selecting merge displays that merging is not yet supported and changes
    nothing. Cancelling also changes nothing.

### Validation and errors

12. Malformed JSON, unsupported format versions, unknown fields, missing required
    data, invalid field values and unresolved relationships cause the entire
    import to fail.
13. Each failed import displays **"Import niet gelukt"** and a concrete cause.
14. A failed new-school import adds nothing. A failed replacement preserves the
    entire existing school. Other schools are unaffected in either case.
15. After a failure, the user can select a corrected file and retry.

### Round-trip integrity

16. Exporting and importing a school preserves every configured field and
    relationship, including a dancer's membership in multiple groups, shows and
    their day parts, and any existing coaches or day-part group assignments.
17. Exporting the restored school again preserves its unique school key and
    equivalent configuration, even if internal numeric IDs changed.

## Implementation handoff

This specification records agreed behavior. Backend endpoints, the detailed JSON
schema and frontend implementation remain implementation work; this review does
not implement the feature.