Vollständiges Datenmodell: JSON-Entitäten, Beziehungen und Ontologie

Diese Seite beschreibt das vollständige Datenmodell eines Omniscol-Kontos: die Entitäten, ihre wichtigsten Felder und ihre Beziehungen. Sie ergänzt die konzeptionelle Seite Datenorganisation, die das Warum erklärt (Schulreferenz ↔ Stundenplan, lokale Kopien); hier geht es um das Was — eine strukturelle, nutzbare Kartierung, insbesondere um das Modell mit einer externen Referenz zu verknüpfen (Verwaltungssoftware, Verzeichnis, Informationssystem).

Technische Seite. Diese Referenz richtet sich an die Integration und die Abstimmung mit einem externen System. Sie ist für den täglichen Gebrauch von Omniscol nicht erforderlich: Um die Organisation der Daten auf fachlicher Seite zu verstehen, siehe Datenorganisation.

Alle Daten einer Einrichtung sind als Baum organisiert. Die unten beschriebenen Entitäten (Benutzer, Schuljahre, Stundenpläne, Abwesenheiten, Ereignisse usw.) entsprechen den verschiedenen Zweigen dieser Struktur. Die normative Referenz ist das JSON-Schema des Kontos. Es lässt sich in zwei Formen einsehen:

• die Rohquelle (das JSON-Schema als solches), die das Konto unter https://api.omniscol.com/api/guest/school_schema.json bereitstellt;
• die Baumansicht, lesbar unter omniscol.com/de/datamodel (und die entsprechende API-Referenz unter omniscol.com/de/developers).

Dieses Schema beschreibt exakt die physische Speicherung in der Datenbank als JSON-Dokument. Diese Seite bietet eine geordnete und über die Zeit stabile Lesart davon.

Das Schuldokument: die Wurzel

Das Wurzeldokument fasst die dauerhafte Referenz der Einrichtung und all ihre Planungsdaten zusammen. Seine Teilbäume erster Ebene:

Die als „Wörterbuch“ ausgedrückten Teilbäume sind JSON-Objekte, deren Schlüssel stabile Identifikatoren sind (der Angelpunkt jeder externen Verknüpfung — siehe den Schlussabschnitt).

Übergreifende Felder: _extids und wishes

Zwei Felder tauchen bei vielen Entitäten auf. Um sie nicht in jedem Schema zu wiederholen, werden sie hier einmalig beschrieben.

• _extids (ExternalIds) — Tabelle der Identifikatoren der Entität in externen Systemen, zum Beispiel { "auriga": "12345" }. Vorhanden bei synchronisierbaren Entitäten (Fächer, Familien, Benutzer, Standorte, Räume, Ressourcen, Lehrkräfte, Klassen, Gruppen…). Es ist der Ankerpunkt für die Abstimmung mit einer externen Referenz (siehe den Schlussabschnitt).
• wishes — zeitliche Einschränkungen: Verfügbarkeiten, gewünschte oder zu vermeidende Zeitfenster, maximales Stundenvolumen, bevorzugter Raum… Vorhanden bei den meisten planbaren Entitäten: Benutzer, Lehrkräfte und Fächer eines Stundenplans, Gruppen, Klassen, Räume, Zeitfenster eines Standorts, Aufsichtsraster. Je nach Geltungsbereich sind diese Einschränkungen global (Schulebene) oder für einen Stundenplan spezifisch.

Ebene 1 — Die Schulreferenz

Die Schulreferenz enthält, was für die Einrichtung gilt, unabhängig von einem Stundenplan: den Fächerkatalog, das Benutzerverzeichnis, den Kalender der Schuljahre.

Fächer — SubjectFull / Subject / Family

Ein benutzerdefiniertes Fach (SubjectFull) erweitert das Basisfach (Subject: name, short, code, type, _extids) um parent, family und color. Auf Schulebene bestehen zwei Ursprünge nebeneinander: die gemeinsamen Fächer des Landes (schreibgeschützt) und die benutzerdefinierten Fächer der Einrichtung. Funktionale Details: Fächer verwalten.

Benutzer — User (einschließlich der Lehrkräfte)

Ein User ist die einzige Entität des Verzeichnisses: Identität (Name, Vorname, idnumber, Kontakt), Authentifizierung (login), roles, Referenz-Deputatsstunden (servicehours), globale Verfügbarkeiten (Feld wishes) und placements. Eine Lehrkraft ist keine eigene Entität: Es ist ein User, der teacher unter seinen roles führt (ein und derselbe Benutzer kann mehrere Rollen vereinen). Das Feld placements (nach Schuljahr indiziert) ordnet einen Schüler über einen Zeitraum einer class und groups zu. Details: Lehrkräfte verwalten.

Schuljahre — SchoolYear / Holiday

Ein SchoolYear definiert date_start → date_end, die Liste der holidays und die altweeks (Wechselwochen). Es ist ein zeitlicher Rahmen, kein Container: Die Stundenpläne entfalten sich darin, ohne darin verschachtelt zu sein. Siehe Schuljahr.

Ebene 2 — Der Stundenplan

Ein Timetable ist eine kohärente Planungseinheit. Er trägt seine eigene lokale Kopie der Lehrkräfte, Klassen, Gruppen und Fächer — siehe das Prinzip der lokalen Kopie in Datenorganisation.

Konfiguration — TimetableConfig

Das entscheidende Feld ist type: week (wöchentlich wiederholt), cycle (mehrtägiger Zyklus, siehe cycle) oder calendar (reale Daten, siehe dates). time_period und time_unit definieren das Gerüst des Rasters; weekdays die Arbeitstage; date_windows die Einschränkungsfenster für die automatische Generierung.

Standorte, Räume, Ressourcen

Ein TimetableSite (Standort) enthält seine classrooms (TimetableClassroom: capacity, specialisation, maxclasses, building) und seine resources (TimetableResource: number = verfügbare Menge, für die das System die Nicht-Überbelegung sicherstellt). distances modelliert die Fahrzeiten zwischen Standorten. Siehe Standorte, Räume und Ressourcen und Raumtypen.

Lehrkräfte des Stundenplans — TimetableTeacher

Angereicherte partielle Kopie eines User: Nur einige identifizierende Felder werden übernommen (first_name, last_name, idnumber), ergänzt um planungsspezifische Felder (überschreibbare servicehours, bevorzugter classroom, wishes pro Stundenplan). Ein nicht leerer virtual_name bezeichnet eine virtuelle Lehrkraft (eine zu besetzende Stelle, ohne echten User dahinter).

Klassen, Klassenfächer, Gruppen

• TimetableClass: name, level, campus/sites, studentsnb, und drei Schlüssel-Teilbäume — subjects, groups, courses.
• TimetableClassSubject: lokale Kopie eines Fachs (erweitert Subject), für die Planung angereichert — minutes (angestrebtes Volumen), pweight (pädagogisches Gewicht), incompatibilities, Standard-teachers, Raum-specialisation. Ein Fach mit einer Unterrichtsart zuzuweisen erzeugt einen eigenen Eintrag pro Art. Siehe Kurse, Unterrichtsstunden, Unterrichtsarten.
• TimetableClassGroup: eine Teilmenge einer Klasse. free=true deaktiviert die Konflikte mit dem Rest der Klasse (freie Gruppe); parent legt die gruppenhierarchie fest.

Regeln zwischen Gruppen — Klassenteilungen, Ausrichtungen, Gruppen von Gruppen

Die Beziehungen zwischen Gruppen werden vom Teilbaum groups des Stundenplans getragen, in drei Formen:

Siehe auch die Übersicht Klasse, Gruppe, Untergruppe.

Ebene 3 — Die Unterrichtsstunden

Eine Unterrichtsstunde (Lesson) ist die tatsächlich im Stundenplan platzierte Unterrichtseinheit: Dauer, Fach, Gruppe, Lehrkraft(en), Raum, Ressourcen, Position und Status. Sie wird aus einem Klassenfach (siehe Ebene 2) generiert und entweder einer Klasse (class.courses) oder direkt dem Stundenplan (timetable.lessons) zugeordnet — Letzteres im Fall von Gruppen von Gruppen und mehrere Klassen umfassenden Unterrichtsstunden mit mehreren Gruppen.

Kern einer Unterrichtsstunde

Eine Unterrichtsstunde trägt die Planungsfelder — duration (in Perioden), duration_actual / duration_accounted (tatsächliche / abgerechnete Minuten), modality, subject, group, teachers, classroom, resources — ergänzt um ihre position, ihren status, ihre memos und eine Identität (_id, _osrev). teachers oder classroom auf null zu setzen erzwingt ausdrücklich das Fehlen einer Lehrkraft oder eines Raums.

Komplexe Unterrichtsstunden

Eine Unterrichtsstunde kann weitere zusammenfassen:

• assoc — verknüpfte Unterrichtsstunden: Die Gruppen tauschen gemeinsam.
• concat — aneinandergereihte Unterrichtsstunden: strikt aufeinanderfolgend.
• weekalt — Wechselwochen: eine Variante der Unterrichtsstunde je Woche.

Diese Mechanismen decken die komplexen Unterrichtsstunden ab — siehe Komplexe Unterrichtsstunden: im Wechsel, verknüpft, aneinandergereiht.

Position einer Unterrichtsstunde

Die position ist ein Objekt, das die Unterrichtsstunde zeitlich einordnet. Es fasst die folgenden Felder zusammen:

• position.day — der Tag der Unterrichtsstunde, polymorph je nach Modus des Stundenplans: ein Tagesname (monday…sunday) im Wochenmodus, eine Nummer des Zyklustags ("1", "2"…) im zyklischen Modus, oder ein Datum YYYY-MM-DD im Kalendermodus. Es ist ein und dasselbe Feld, das je nach Modus seine Form ändert; es ist stets vorhanden.
• position.period — der Index des Zeitfensters im Zeitraster. Eine Unterrichtsstunde ohne period und ohne start/end entspricht einem Feiertag.
• position.start / position.end — exakte Start- und Endzeiten (HH:MM), für Unterrichtsstunden außerhalb des Rasters oder im Kalendermodus, die sich nicht an einem Standard-Zeitfenster ausrichten.
• position.fixed — Boolescher Wert (standardmäßig falsch): eine angepinnte Unterrichtsstunde, die die automatische Generierung nicht verschiebt.

Die Unterrichtsstunden einer Klasse leben in class.courses; das Array timetable.lessons trägt die klassenübergreifenden Unterrichtsstunden, die mit den Gruppen von Gruppen verbunden sind.

Identität einer Unterrichtsstunde

Jede Unterrichtsstunde trägt zwei technische Identitätsfelder, vorhanden auf Premium-Konten:

• _id — stabiler Identifikator, bei der Erstellung der Unterrichtsstunde vergeben und danach unveränderlich (er kombiniert einen Zeitstempel und einen Fingerabdruck des Inhalts). Er ist der Schlüssel einer Unterrichtsstunde für die kollaborative Bearbeitung und für ein externes Werkzeug, das die Unterrichtsstunden im Zeitverlauf verfolgt. Für die wiederkehrenden Vorkommen eines Kalender-Stundenplans (Wechselwochen, Aneinanderreihungen, Verknüpfungen) wird der _id jedes Vorkommens von dem der Basis-Unterrichtsstunde abgeleitet, die erkennbar bleibt.
• _osrev — Revisions-Token (optimistische Sperrung), bei jeder Änderung inkrementiert (Zeitstempel + Änderungsindex), in strikt alphabetischer Reihenfolge (was es leicht macht zu erkennen, ob eine Revision aktueller ist als eine andere). Es ermöglicht der kollaborativen Bearbeitung, gleichzeitige Änderungen zu erkennen und zusammenzuführen: eine veraltete Client-Revision signalisiert einen Konflikt, den der Server auflöst oder zusammenführt, statt stillschweigend zu überschreiben.

Abwesenheiten

Die Abwesenheiten teilen eine gemeinsame Basis (Absence: date_start, date_end, reason, hours, comment, Status), spezialisiert je nach Betroffenem.

Eine AbsenceTeacher kann auf bestimmte subjects/classes beschränkt sein und trägt ein Array von Vertretungsregeln (substitutes, jede eine AbsenceTeacherSubstitute: Vertretung, Zeitraum, Zeitfenster, abgedeckte Klassen und Fächer). Die Status unterscheiden sich je nach Betroffenem (zum Beispiel ok/aborted für eine Klasse). Siehe den Glossareintrag Vertretung und das Modul Abwesenheitsverwaltung.

Personalmitglieder

Eigenständiges Modul (auch einzeln vertrieben) für die Aufsicht und die Betreuungsdienste.

Ein StaffingGrid ist die Vorlage (Tage, Perioden); die assignments beschreiben die Stellen (req/ideal, priority, nach Zeitfenster detaillierte needs über StaffingNeedSpan); der schedule materialisiert die tatsächlichen Dienste nach Datum. Siehe das Modul Personaleinsatz.

Ereignisse

Ein Event ist ein über das Raster gelegter Terminkalendereintrag: etwas, das in der Einrichtung geschieht, ohne eine reguläre Unterrichtsstunde zu sein — eine Klassenkonferenz, ein Elternabend, eine eintägige Prüfung, ein Ausflug, ein Tag der offenen Tür. Die Ereignisse werden im Wörterbuch events abgelegt (Schlüssel event-<n>) und gehören zu den Premium-Funktionen.

Felder eines Event (obligatorisch: title, start, end):

• title — angezeigter Titel.
• start / end — Beginn und Ende, im Format YYYYMMDDTHHmmSS.
• rrule — eventuelle Wiederholungs-Regel.
• attendees — Teilnehmer: ein Benutzer, eine Klasse, eine Gruppe, eine freie Bezeichnung (custom), oder die gesamte Einrichtung (everybody) / jede freiwillige Person (anyone).
• location — Ort(e): ein Raum des Stundenplans oder eine freie Bezeichnung.
• resources — für das Ereignis reservierte Ressourcen.
• videolink — Videokonferenzlink, um aus der Ferne teilzunehmen.
• memos — Kommentare; color — Farbe (hexadezimal).

Die Funktionsweise im Gebrauch (Erstellung, Platzierung auf dem Raster, Felder der Oberfläche) wird in Punktuelle Ereignisse beschrieben.

Anzeigetafeln

Ein Panel ist eine Anzeigetafel der Unterrichtsstunden des Tages (Eingangshalle, Raum, Willkommensbildschirm…). Es definiert die Auswahl der columns, die topline, die filters/exclusions sowie Erscheinungseinstellungen. Siehe den Glossareintrag Anzeigetafel.

Identifikatoren, lokale Kopien und Verknüpfung mit einem ERP

Um das Omniscol-Modell mit einer externen Referenz zu verbinden, haben drei Prinzipien Vorrang:

1. Die Wörterbuchschlüssel sind die stabilen Identifikatoren. Die Fächer, Benutzer, Lehrkräfte, Klassen, Gruppen, Räume, Ressourcen werden über einen unveränderlichen Identifikator (den JSON-Schlüssel) indiziert, nicht über ihre Bezeichnung. Genau dieser Angelpunkt — niemals der name — ist es, der für jede Zuordnung zu verwenden ist.

2. Das Feld _extids (ExternalIds) trägt die externen Identifikatoren. Vorhanden bei synchronisierbaren Entitäten (Subject, Family, TimetableSite, TimetableClassroom, TimetableResource, TimetableTeacher, TimetableClass, TimetableClassGroup, User…), verbindet es jede Entität mit ihren Identifikatoren in Drittsystemen, zum Beispiel { "auriga": "12345", "aimaira": "67890" }. Es ist der kanonische Ankerpunkt einer bidirektionalen Abstimmung.

3. Die lokale Kopie Schule ↔ Stundenplan ist gewollt. Ein Klassenfach oder eine Lehrkraft eines Stundenplans ist eine angereicherte Kopie, keine lebende Referenz. Eine externe Referenz muss daher entscheiden, auf welcher Ebene sie sich abstimmt: die Schulreferenz (dauerhafter Katalog) oder ein bestimmter Stundenplan (datierte Planung). Die Einzelheiten der Propagierungsregeln stehen in Datenorganisation.

Die Konfiguration der Synchronisation befindet sich in config.extsync (SchoolConfigExtsync): systems (konfigurierte Konnektoren), sync (Richtung und Entitäten), export und schedules, sowie Zuordnungstabellen (mappings) nach Schlüssel und Omniscol-Identifikator. Für den programmatischen Zugriff werden die REST-API und die Tokens in API-Tokens beschrieben; die Synchronisationskonnektoren in Externe Synchronisation.

Die genaue und vollständige Form jedes Felds bleibt durch das Referenz-JSON-Schema des Kontos definiert (https://api.omniscol.com/api/guest/school_schema.json, lesbare Ansicht unter omniscol.com/de/datamodel). Bei Abweichung zwischen dieser Seite und dem Schema gilt das Schema.