agiledancers/specs/School-JSON-format.md

School JSON format, version 1

Export: GET /api/dance-schools/{id}/export downloads readable JSON. Preview: POST /api/dance-schools/import/preview accepts the file itself as application/json, validates without writing, and returns name, dancers, groups, shows, existingId and existingName. Commit: POST /api/dance-schools/import accepts the same file. For replacement, provide ?replaceId=<existingId> as explicit confirmation. A mismatch is rejected; refresh the preview if another import added or removed the school meanwhile. There is no merge endpoint.

{
  "formatVersion": 1,
  "key": "1b8fe22c-5ac3-4ab9-a2c8-d1d28d2becee",
  "name": "Studio",
  "dancers": [{ "id": "d1", "name": "Sam", "birthDate": "2010-05-12" }],
  "coaches": [{ "id": "c1", "name": "Alex" }],
  "groups": [{
    "id": "g1", "category": "Hiphop", "type": "REGULAR",
    "startAge": 12, "endAge": 18, "styles": ["HIPHOP"],
    "dancerIds": ["d1"], "coachId": "c1"
  }],
  "shows": [{
    "id": "s1", "name": "Summer show", "date": "2027-06-12",
    "dayParts": [{ "type": "MORNING", "groupIds": ["g1"] }]
  }]
}

key is a persistent UUID independent of the server's numeric school ID. IDs inside each collection are nonblank strings, unique within that collection, and local to this file. They can change on export. References must resolve within the file. A dancer or coach can be referenced by multiple groups. A group can appear in multiple day parts. A day-part type can occur once per show.

All fields are required except coachId, which may be absent or null. Collections may be empty. Names/category must be nonblank. Dates use ISO yyyy-MM-dd; birth dates cannot be in the future. Ages are nonnegative integers with startAge <= endAge. Enum values use the same uppercase names as the management API. Day-part types are MORNING, AFTERNOON, EVENING. Unknown fields, duplicate JSON properties, duplicate IDs or references, invalid values and unsupported versions are rejected. Validation is repeated on commit. The entire school is prepared before publishing it under the shared service lock. Replacing retains the numeric school ID for existing browser links; imported child IDs are reassigned to avoid collisions with other schools.

Group types: SHOW_CASE, PRE_EDUCATION, SELECTION, REGULAR, PRE_SCHOOLER. Styles: HIPHOP, JAZZ, MODERN, STREETDANCE, CLASSIC, BREAKDANCE.