API and Data Contract

A proposal, not a decision. Every entity and relationship below is open to challenge; the open decisions are listed at the end.

Version 0.3, 6 September 2026 (0.1 and 0.2 earlier the same day; changes listed at the end). The single agreement between the engine track (backend, solver) and the experience track (UI, flows). Both build against this document. Any change to a shape or endpoint is made here first, by whoever needs it, with a version bump, and the other track is told.

Overview

The contract has two halves: the JSON shapes of the domain objects, taken from the domain model proposal, and the HTTP endpoints through which a client reads and writes them and asks for a timetable. The engine implements the endpoints; the experience track stubs them with the same shapes until integration.

Summary

• Every object has a string id, a display name, and where a Hebrew display name exists, nameHe. Times are ISO 8601 strings. Enumerations are lowercase strings.
• A School owns everything else. All collection endpoints are scoped by school.
• The unit of scheduling is the Event. A Timetable is a versioned set of Assignments of events to slots, with Violations against Constraints.
• Solving is asynchronous: POST /solve returns a Job; the client polls it and reads the resulting timetable. Repair is the same call with pinned assignments and a basedOn timetable.
• Errors are JSON { "error": { "code": string, "message": string, "details"?: object } } with HTTP 4xx or 5xx.

Bottom line

Version 0.1 covers what Mevo Hagalil needs: staff with availability, classes and student groups, subjects, a curriculum, events with staff slots, constraints traceable to requirement IDs, and timetables with violations and pinning. Rooms and students are present in the shapes but optional everywhere.

Detailed explanation

Shapes

{
  "School": {
    "id": "mevo-hagalil", "name": "Mevo Hagalil", "nameHe": "מבוא הגליל",
    "sector": "state", "stage": "primary",
    "timeGrid": {
      "days": ["sun", "mon", "tue", "wed", "thu"],
      "periodsPerDay": {"sun": 7, "mon": 7, "tue": 5, "wed": 7, "thu": 7},
      "longDayPeriod": 7,
      "clockTimes": [{"period": 1, "start": "08:00", "end": "08:45"}],
      "breaks": [{"afterPeriod": 2, "start": "09:25", "end": "09:55", "kind": "break", "name": "Breakfast and break", "nameHe": "ארוחת בוקר והפסקה"}]
    }
  },
  "RoomType": {"id": "science", "schoolId": "mevo-hagalil", "name": "Science room", "nameHe": "חדר מדעים"},
  "Room": {"id": "r-science", "schoolId": "mevo-hagalil", "roomTypeId": "science", "name": "Science room", "nameHe": "חדר מדעים", "ownerStaffIds": ["s-keren-s", "s-shirly"]},
  "Grade": {"id": "g3", "schoolId": "mevo-hagalil", "level": 3, "name": "Grade 3", "nameHe": "מחזור ג'"},
  "Class": {"id": "c-3-nesher", "schoolId": "mevo-hagalil", "gradeId": "g3", "name": "3 Nesher", "nameHe": "ג' נשר", "homeroomStaffId": "s-idit"},
  "StudentGroup": {
    "id": "sg-3-nesher", "schoolId": "mevo-hagalil",
    "kind": "class",            
    "classIds": ["c-3-nesher"],
    "name": "3 Nesher", "nameHe": "ג' נשר",
    "studentIds": []
  },
  "Staff": {
    "id": "s-idit", "schoolId": "mevo-hagalil",
    "name": "Idit Tamir", "nameHe": "תמיר עידית", "shortNameHe": "עידית",
    "role": "teacher",          
    "contract": "ofek-hadash",
    "hours": {"frontal": 23, "individual": 4, "staying": 9, "derived": true},
    "subjectIds": ["math", "hebrew"],
    "homeroomClassId": "c-3-nesher",
    "availability": [
      {"day": "tue", "period": null, "state": "unavailable", "reason": "part-time"},
      {"day": "mon", "period": 5, "state": "unavailable", "reason": "meeting: grade 3 team"}
    ]
  },
  "Subject": {"id": "math", "schoolId": "mevo-hagalil", "name": "Mathematics", "nameHe": "חשבון", "isCore": true, "roomTypeId": null},
  "CurriculumLine": {
    "id": "cl-g3-math", "schoolId": "mevo-hagalil", "gradeId": "g3", "subjectId": "math",
    "weeklyPeriods": 5, "pattern": [1, 1, 1, 1, 1],
    "coTeaching": {"required": true, "withHomeroom": true}
  },
  "Event": {
    "id": "ev-3-nesher-math-1", "schoolId": "mevo-hagalil",
    "kind": "lesson",           
    "subjectId": "math",
    "duration": 1,
    "studentGroupIds": ["sg-3-nesher"],
    "staffSlots": [
      {"role": "lead", "staffId": "s-idit"},
      {"role": "co", "staffId": null, "subjectId": "math"}
    ],
    "roomTypeId": null,
    "curriculumLineId": "cl-g3-math",
    "eventGroupId": "eg-3-nesher-math",
    "fixedAt": null,            
    "tags": []
  },
  "EventGroup": {"id": "eg-3-nesher-math", "schoolId": "mevo-hagalil", "kind": "same-course", "eventIds": ["ev-3-nesher-math-1"]},
  "Constraint": {
    "id": "k-r06", "schoolId": "mevo-hagalil",
    "type": "homeroom-starts-first-period",
    "enabled": true,
    "hard": false, "weight": 10,
    "params": {"minDays": 3},
    "appliesTo": {"staffIds": [], "classIds": [], "subjectIds": [], "all": true},
    "implements": ["R-06"],
    "name": "Homeroom starts the day", "nameHe": "מחנכת פותחת את היום"
  },
  "Timetable": {
    "id": "tt-2026-09-03", "schoolId": "mevo-hagalil",
    "version": 3, "status": "draft",
    "basedOnId": "tt-2026-08-30",
    "createdAt": "2026-09-06T10:00:00Z",
    "score": {"hard": 0, "soft": 42},
    "assignments": [
      {"eventId": "ev-3-nesher-math-1", "slots": [{"day": "sun", "period": 2}], "roomId": null, "staffIds": ["s-idit", "s-sapir-h"], "pinned": false}
    ],
    "violations": [
      {"constraintId": "k-r06", "cost": 10, "entityIds": ["s-mor"], "eventIds": [], "slots": [{"day": "tue", "period": 1}], "message": "Mor starts at period 1 on 2 days; the rule asks for 3.", "messageHe": "מור מתחילה בשיעור 1 ב-2 ימים; הכלל דורש 3."}
    ]
  },
  "Job": {"id": "job-123", "kind": "solve", "status": "running", "progress": {"phase": "improving", "elapsedSeconds": 12, "hard": 0, "soft": 57}, "resultTimetableId": null, "error": null}
}

Enumerations:

• StudentGroup.kind: class, half, level, cross, cohort.
• Staff.role: teacher, assistant, soldier, external. Staff.contract: ofek-hadash, oz-latmura, other. Staff.hours.derived marks estimated counts. Availability.reason starting with meeting: counts as busy time for the no-gaps rule.
• Availability.state: unavailable, prefer-not. period: null means the whole day.
• Event.kind: lesson, activity, meeting, individual, staying. Event.fixedAt: null or {"day": "sun", "period": 4} for the first slot of the event.
• StaffSlot.role: lead, co, assistant, soldier. A slot with staffId: null is filled by the solver from staff who teach subjectId (or any staff when subjectId is null).
• EventGroup.kind: same-course (spread across the week), linked (must be simultaneous).
• Timetable.status: draft, published, archived. Job.status: queued, running, done, failed, cancelled.

Constraint types, version 0.3

Each type has fixed params. The engine validates them. The list grows as requirements are confirmed.

Endpoints

Base path /api/v1. All collections support GET (list), POST (create), and GET, PUT, DELETE on /{id}. Lists return {"items": [...], "total": n}.

Conventions for the stub

The experience track ships a stub that implements every endpoint above in memory, seeded with a fixture derived from Mevo Hagalil (data/mevo-hagalil/). POST /solve in the stub returns a Job that moves queued, running, done over a few seconds and produces a timetable equal to the fixture with a handful of synthetic violations, so the review and repair flows can be designed against realistic output.

Open items

• Room assignment is out of scope in 0.1; roomId and roomTypeId are accepted and ignored.
• Non-frontal hours (individual, staying) are events of those kinds only if Q-03 says they must be placed; otherwise they are counts on Staff.
• Authentication and multi-user editing are not in 0.1.

Changes in 0.2

Requested by the experience track after building the prototype; the engine track adopts them in its next iteration.

• Constraint.enabled (boolean, default true): switch a rule off without deleting it.
• Constraint.implements is an array of requirement IDs, since one constraint type can cover several (availability covers R-09, R-10, S-05).
• Violation.eventIds and Violation.slots (optional): the events and grid cells involved, so the UI can focus them. entityIds remains for people and classes.
• POST /timetables/{id}/fork and the rule that a published timetable is immutable.

Changes in 0.3

From Vegman's answers of 6 September (requirements v0.3) and both tracks' implementations.

• TimeGrid.breaks[] with afterPeriod, start, end, kind, name, nameHe (S-16).
• RoomType and Room with ownerStaffIds, plus their endpoints (S-13). Room assignment itself is still out of scope; rooms carry sharing rules only.
• Staff.hours.derived for estimated counts while the teacher table is confidential (Q-02); Staff.role gains external (S-15).
• New constraint types room-shared-owners and room-owner-whole-class; new parameters on no-gaps, ends-long-day, subject-per-day, avoid-last-period, homeroom-starts-first-period as listed in the table.
• Availability.reason values starting with meeting: count as busy for the no-gaps rule (S-05, S-11).
• Open staff slots (staffId: null) are legal in a published timetable and never produce clashes (S-14).

{
  "School": {
    "id": "mevo-hagalil", "name": "Mevo Hagalil", "nameHe": "מבוא הגליל",
    "sector": "state", "stage": "primary",
    "timeGrid": {
      "days": ["sun", "mon", "tue", "wed", "thu"],
      "periodsPerDay": {"sun": 7, "mon": 7, "tue": 5, "wed": 7, "thu": 7},
      "longDayPeriod": 7,
      "clockTimes": [{"period": 1, "start": "08:00", "end": "08:45"}]
    }
  },
  "Grade": {"id": "g3", "schoolId": "mevo-hagalil", "level": 3, "name": "Grade 3", "nameHe": "מחזור ג'"},
  "Class": {"id": "c-3-nesher", "schoolId": "mevo-hagalil", "gradeId": "g3", "name": "3 Nesher", "nameHe": "ג' נשר", "homeroomStaffId": "s-idit"},
  "StudentGroup": {
    "id": "sg-3-nesher", "schoolId": "mevo-hagalil",
    "kind": "class",            
    "classIds": ["c-3-nesher"],
    "name": "3 Nesher", "nameHe": "ג' נשר",
    "studentIds": []
  },
  "Staff": {
    "id": "s-idit", "schoolId": "mevo-hagalil",
    "name": "Idit Tamir", "nameHe": "תמיר עידית", "shortNameHe": "עידית",
    "role": "teacher",          
    "contract": "ofek-hadash",
    "hours": {"frontal": 23, "individual": 4, "staying": 9},
    "subjectIds": ["math", "hebrew"],
    "homeroomClassId": "c-3-nesher",
    "availability": [
      {"day": "tue", "period": null, "state": "unavailable", "reason": "part-time"},
      {"day": "mon", "period": 5, "state": "unavailable", "reason": "meeting: grade 3 team"}
    ]
  },
  "Subject": {"id": "math", "schoolId": "mevo-hagalil", "name": "Mathematics", "nameHe": "חשבון", "isCore": true, "roomTypeId": null},
  "CurriculumLine": {
    "id": "cl-g3-math", "schoolId": "mevo-hagalil", "gradeId": "g3", "subjectId": "math",
    "weeklyPeriods": 5, "pattern": [1, 1, 1, 1, 1],
    "coTeaching": {"required": true, "withHomeroom": true}
  },
  "Event": {
    "id": "ev-3-nesher-math-1", "schoolId": "mevo-hagalil",
    "kind": "lesson",           
    "subjectId": "math",
    "duration": 1,
    "studentGroupIds": ["sg-3-nesher"],
    "staffSlots": [
      {"role": "lead", "staffId": "s-idit"},
      {"role": "co", "staffId": null, "subjectId": "math"}
    ],
    "roomTypeId": null,
    "curriculumLineId": "cl-g3-math",
    "eventGroupId": "eg-3-nesher-math",
    "fixedAt": null,            
    "tags": []
  },
  "EventGroup": {"id": "eg-3-nesher-math", "schoolId": "mevo-hagalil", "kind": "same-course", "eventIds": ["ev-3-nesher-math-1"]},
  "Constraint": {
    "id": "k-r06", "schoolId": "mevo-hagalil",
    "type": "homeroom-starts-first-period",
    "enabled": true,
    "hard": false, "weight": 10,
    "params": {"minDays": 3},
    "appliesTo": {"staffIds": [], "classIds": [], "subjectIds": [], "all": true},
    "implements": ["R-06"],
    "name": "Homeroom starts the day", "nameHe": "מחנכת פותחת את היום"
  },
  "Timetable": {
    "id": "tt-2026-09-03", "schoolId": "mevo-hagalil",
    "version": 3, "status": "draft",
    "basedOnId": "tt-2026-08-30",
    "createdAt": "2026-09-06T10:00:00Z",
    "score": {"hard": 0, "soft": 42},
    "assignments": [
      {"eventId": "ev-3-nesher-math-1", "slots": [{"day": "sun", "period": 2}], "roomId": null, "staffIds": ["s-idit", "s-sapir-h"], "pinned": false}
    ],
    "violations": [
      {"constraintId": "k-r06", "cost": 10, "entityIds": ["s-mor"], "eventIds": [], "slots": [{"day": "tue", "period": 1}], "message": "Mor starts at period 1 on 2 days; the rule asks for 3.", "messageHe": "מור מתחילה בשיעור 1 ב-2 ימים; הכלל דורש 3."}
    ]
  },
  "Job": {"id": "job-123", "kind": "solve", "status": "running", "progress": {"phase": "improving", "elapsedSeconds": 12, "hard": 0, "soft": 57}, "resultTimetableId": null, "error": null}
}