S19: establish landscape repository

specs/School-JSON-format.md

@@ -0,0 +1,58 @@
+# School JSON format, version 3
+
+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.
+
+```json
+{
+  "formatVersion": 3,
+  "key": "1b8fe22c-5ac3-4ab9-a2c8-d1d28d2becee",
+  "name": "Studio",
+  "dancers": [{ "id": "d1", "name": "Sam", "birthDate": "2010-05-12" }],
+  "coaches": [{ "id": "c1", "name": "Alex", "dancerId": "d1" }],
+  "groups": [{
+    "id": "g1", "category": "Hiphop", "type": "REGULAR",
+    "startAge": 12, "endAge": 18, "styles": ["HIPHOP"],
+    "dancerIds": ["d1"], "coachId": "c1"
+  }],
+  "shows": [{
+    "id": "s1", "name": "Summer show", "preferredDayParts": 1, "finalized": false,
+    "dayParts": [{ "date": "2027-06-12", "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 date/type combination can occur once per show, with at most six dayparts.
+
+The optional `coachId` and coach `dancerId` references may be absent or null.
+`preferredDayParts` defaults to two (one for a single daypart); `finalized`
+defaults to false. Legacy version 2 files remain supported; version 1 is rejected.
+Legacy `appearances` counts may be present but do not govern S18 scheduling.
+Every imported schedule becomes a draft, even when exported as final.
+`preferredDayParts` must be an integer from one to six; a retained value exceeding
+the daypart count must be corrected before scheduling or finalization. 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 membership 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`.
+
+
+Affected repositories: `agiledancers`.