Volledig gegevensmodel: JSON-entiteiten, relaties en ontologie

Deze pagina beschrijft het volledige gegevensmodel van een Omniscol-account: de entiteiten, hun belangrijkste velden en hun onderlinge relaties. Ze bouwt voort op de conceptuele pagina Organisatie van de gegevens, die het waarom uitlegt (schoolregister ↔ rooster, lokale kopieën); hier gaat het om het wat — een bruikbare structurele kaart, met name om het model te koppelen aan een extern register (ERP-pakket, directoryservice, informatiesysteem).

Technische pagina. Deze naslag is bedoeld voor integratie en voor het afstemmen op een extern systeem. Ze is niet nodig voor het dagelijkse gebruik van Omniscol: zie Organisatie van de gegevens om te begrijpen hoe de gegevens aan de functionele kant zijn geordend.

Alle gegevens van een instelling zijn als een boomstructuur georganiseerd. De hieronder beschreven entiteiten (gebruikers, schooljaren, roosters, afwezigheden, evenementen enzovoort) komen overeen met de verschillende takken van die structuur. De normatieve referentie is het JSON-schema van het account. Dat is in twee vormen te raadplegen:

• de onbewerkte bron (het JSON-schema als zodanig), die het account aanbiedt op https://api.omniscol.com/api/guest/school_schema.json;
• de leesbare boomweergave op omniscol.com/nl/datamodel (en de bijbehorende API-referentie op omniscol.com/nl/developers).

Dat schema beschrijft precies de fysieke opslag in de database, in de vorm van een JSON-document. Deze pagina biedt daarvan een geordende lezing die in de tijd stabiel blijft.

Het schooldocument: de root

Het rootdocument bundelt het duurzame register van de instelling en al haar planningen. De deelbomen op het eerste niveau:

De deelbomen die als “woordenboek” zijn aangeduid, zijn JSON-objecten waarvan de sleutels stabiele identificaties zijn (het draaipunt van elke externe koppeling — zie de slotsectie).

Overkoepelende velden: _extids en wishes

Twee velden komen op veel entiteiten terug. Om ze niet in elk schema te herhalen, worden ze hier één keer beschreven.

• _extids (ExternalIds) — tabel met de identificaties van de entiteit in de externe systemen, bijvoorbeeld { "auriga": "12345" }. Aanwezig op de synchroniseerbare entiteiten (vakken, families, gebruikers, vestigingen, lokalen, resources, docenten, klassen, groepen…). Dat is het ankerpunt voor de koppeling met een extern register (zie de slotsectie).
• wishes — tijdsbeperkingen: beschikbaarheid, gewenste of te vermijden tijdslots, maximaal aantal lesuren, voorkeurslokaal… Aanwezig op de meeste planbare entiteiten: gebruikers, docenten van een rooster, cursussen (vakken van de klas), groepen, klassen, lokalen, openingstijden van een vestiging, begeleidingsrasters. Afhankelijk van het bereik gelden die beperkingen globaal (schoolniveau) of alleen binnen één rooster.

Niveau 1 — Het schoolregister

Het schoolregister bevat wat waar is voor de instelling, los van welk rooster dan ook: de vakkencatalogus, de gebruikerslijst, de kalender van de schooljaren.

Vakken — SubjectFull / Subject / Family

Een aangepast vak (SubjectFull) breidt het basisvak (Subject: name, short, code, type, _extids) uit met parent, family en color. Op schoolniveau bestaan er twee herkomsten naast elkaar: de gemeenschappelijke vakken van het land (alleen-lezen) en de aangepaste vakken van de instelling. Functionele details: Vakken beheren.

Gebruikers — User (inclusief de docenten)

Een User is de enige entiteit van de gebruikerslijst: identiteit (achternaam, voornaam, idnumber, contactgegevens), authenticatie (login), roles, diensturen ter referentie (servicehours), globale beschikbaarheid (veld wishes) en placements. Een docent is geen afzonderlijke entiteit: het is een User met teacher bij zijn roles (dezelfde gebruiker kan meerdere rollen combineren). Het veld placements (geïndexeerd per schooljaar) koppelt een leerling aan een class en aan groups over een bepaalde periode. Details: Docenten beheren.

Schooljaren — SchoolYear / Holiday

Een SchoolYear legt date_start → date_end vast, de lijst met holidays en de altweeks (afwisselende weken). Het is een tijdskader, geen container: de roosters ontvouwen zich erbinnen zonder erin genest te zijn. Zie Schooljaar.

Niveau 2 — Het rooster

Een Timetable is een samenhangende planningseenheid. Het draagt zijn eigen lokale kopie van de docenten, klassen, groepen en vakken — zie het principe van de lokale kopie in Organisatie van de gegevens.

Configuratie — TimetableConfig

Het bepalende veld is type: week (wekelijks herhaald), cycle (cyclus over meerdere dagen, zie cycle) of calendar (werkelijke data, zie dates). time_period en time_unit bepalen het stramien van het rooster; weekdays de werkdagen; date_windows de datumvensters die de automatische roostergeneratie beperken.

Vestigingen, lokalen, resources

Een TimetableSite (vestiging) bevat zijn classrooms (TimetableClassroom: capacity, specialisation, maxclasses, building) en zijn resources (TimetableResource: number = beschikbaar aantal, waarbij het systeem overboeking voorkomt). distances modelleert de reistijden tussen vestigingen. Zie Vestigingen, lokalen en resources en Lokaalspecialisaties.

Docenten van het rooster — TimetableTeacher

Verrijkte gedeeltelijke kopie van een User: alleen enkele identificerende velden worden overgenomen (first_name, last_name, idnumber), aangevuld met velden die eigen zijn aan de planning (overschrijfbare servicehours, classroom als voorkeurslokaal, wishes per rooster). Een niet-lege virtual_name duidt een virtuele docent aan (een nog in te vullen functie, zonder echte User erachter).

Klassen, vakken van de klas, groepen

• TimetableClass: name, level, campus/sites, studentsnb, en drie belangrijke deelbomen — subjects, groups, lessons.
• TimetableClassSubject: lokale kopie van een vak (breidt Subject uit), verrijkt voor de planning — minutes (beoogd aantal lesuren), pweight (pedagogisch gewicht), incompatibilities, standaard teachers, specialisation van het lokaal. Een vak toewijzen met een lestype maakt een afzonderlijke vermelding per type aan. Zie Cursussen, lessen, lestypes.
• TimetableClassGroup: een deelverzameling van een klas. free=true schakelt de conflicten met de rest van de klas uit (vrije groep); parent brengt de groepshiërarchie tot stand.

Regels tussen groepen — klasverdelingen, groepsuitlijningen, groepen van groepen

De relaties tussen groepen zitten in de deelboom groups van het rooster, in drie vormen:

Zie ook het overzicht Klas, groep, subgroep.

Niveau 3 — De lessen

Een les (Lesson) is de onderwijseenheid die daadwerkelijk in het rooster wordt geplaatst: duur, vak, groep, docent(en), lokaal, resources, positie en status. Ze wordt aangemaakt vanuit een vak van een klas (zie niveau 2) en hangt ofwel aan een klas (class.lessons), ofwel rechtstreeks aan het rooster (timetable.lessons) — dat laatste geval voor de groepen van groepen en voor de lessen met meerdere groepen, die verschillende klassen overstijgen.

De kern van een les

Een les draagt de planningsvelden — duration (in periodes), duration_actual / duration_accounted (werkelijke / gefactureerde minuten), modality, subject, group, teachers, classroom, resources — aangevuld met haar position, haar status, haar memos en een identiteit (_id, _osrev). teachers of classroom op null zetten forceert uitdrukkelijk dat er geen docent of geen lokaal is.

Complexe lessen

Eén les kan er meerdere samenbrengen:

• assoc — gekoppelde lessen: de groepen wisselen samen.
• concat — aaneengeschakelde lessen: strikt op elkaar volgend.
• weekalt — afwisselende weken: één lesvariant per week.

Die mechanismen dekken de complexe lessen — zie Complexe lessen: afwisselend, gekoppeld, aaneengeschakeld.

De positie van een les

De position is een object dat de les in de tijd plaatst. Het bundelt de volgende velden:

• position.day — de dag van de les, polymorf naargelang de modus van het rooster: een dagnaam (monday…sunday) in de weekmodus, een nummer van de cyclusdag ("1", "2"…) in de cyclische modus, of een datum YYYY-MM-DD in de kalendermodus. Het is telkens hetzelfde veld dat van vorm verandert naargelang de modus; het is altijd aanwezig.
• position.period — de index van het tijdslot in het tijdraster. Een les zonder period en zonder start/end komt overeen met een feestdag.
• position.start / position.end — exacte begin- en eindtijd (HH:MM), voor lessen buiten tijdraster of in kalendermodus die niet op een standaardtijdslot vallen.
• position.fixed — booleaanse waarde (standaard onwaar): een vergrendelde les, die door de automatische roostergeneratie niet wordt verplaatst.

De lessen van een klas staan in class.lessons; de array timetable.lessons draagt de klasoverstijgende lessen die aan de groepen van groepen gekoppeld zijn.

De identiteit van een les

Elke les draagt twee technische identiteitsvelden, aanwezig op Premium-accounts:

• _id — stabiele identificatie, toegekend bij het aanmaken van de les en daarna onveranderlijk (ze combineert een tijdstempel en een vingerafdruk van de inhoud). Het is de sleutel van een les voor het gezamenlijk bewerken en voor een externe toepassing die de lessen in de tijd volgt. Voor de terugkerende voorkomens van een kalenderrooster (afwisselende weken, aaneenschakelingen, koppelingen) is de _id van elk voorkomen afgeleid van die van de basisles, die herkenbaar blijft.
• _osrev — token van de revisie (optimistisch vergrendelen), bij elke wijziging opgehoogd (tijdstempel + wijzigingsindex), in een strikt alfabetische volgorde (waardoor eenvoudig te zien is of de ene revisie recenter is dan de andere). Daardoor kan het gezamenlijk bewerken gelijktijdige wijzigingen opsporen en samenvoegen: een verouderde revisie aan clientzijde wijst op een conflict, dat de server beslecht of samenvoegt in plaats van stilzwijgend te overschrijven.

Afwezigheden

De afwezigheden delen een gemeenschappelijke basis (Absence: date_start, date_end, reason, hours, comment, status), per betrokkene uitgewerkt.

Een AbsenceTeacher kan beperkt worden tot bepaalde subjects/classes en draagt een array met vervangingsregels (substitutes, elk een AbsenceTeacherSubstitute: vervanger, periode, tijdslots, gedekte klassen en vakken). De statussen verschillen per betrokkene (bijvoorbeeld ok/aborted voor een klas). Zie de woordenlijst Vervanging / Invalbeurt en de module Afwezigheidsbeheer.

Personeelsleden

Afzonderlijke module (ook zelfstandig verkocht) voor toezicht en begeleidingstaken.

Een StaffingGrid is het sjabloon (dagen, periodes); de assignments beschrijven de taken (req/ideal, priority, per tijdslot uitgewerkte needs via StaffingNeedSpan); het schedule legt de werkelijke diensten per datum vast. Zie de module Personeelsinzet.

Evenementen

Een Event is een agenda-item dat over het rooster heen wordt gelegd: iets wat in de instelling gebeurt zonder een gewone les te zijn — een rapportvergadering, een ouderavond, een examen van één dag, een excursie, een open dag. De evenementen staan in het woordenboek events (sleutels event-<n>) en horen bij de Premium-functies.

Velden van een Event (verplicht: title, start, end):

• title — weergegeven titel.
• start / end — begin en einde, in het formaat YYYYMMDDTHHmmSS.
• rrule — eventuele regel voor herhaling.
• attendees — deelnemers: een gebruiker, een klas, een groep, een vrij label (custom), of de hele instelling (everybody) / iedereen die wil (anyone).
• location — plaats(en): een lokaal van het rooster of een vrij label.
• resources — resources die voor het evenement zijn gereserveerd.
• videolink — videoconferentielink om op afstand deel te nemen.
• memos — opmerkingen; color — kleur (hexadecimaal).

Hoe dit in de praktijk werkt (aanmaken, op het rooster plaatsen, velden van de interface) wordt beschreven in Eenmalige evenementen.

Informatieschermen

Een Panel is een informatiescherm met de lessen van de dag (hal, lokaal, ingangsscherm…). Het legt de selectie van columns vast, de topline, de filters/exclusions en instellingen voor de weergave. Zie de woordenlijst Informatiescherm.

Identificaties, lokale kopieën en koppeling met een ERP

Om het model van Omniscol aan een extern register te koppelen, gelden drie principes:

1. De sleutels van de woordenboeken zijn de stabiele identificaties. Vakken, gebruikers, docenten, klassen, groepen, lokalen en resources worden geïndexeerd op een onveranderlijke identificatie (de JSON-sleutel), niet op hun label. Dat draaipunt — nooit de name — moet u voor elke overeenkomst gebruiken.

2. Het veld _extids (ExternalIds) draagt de externe identificaties. Aanwezig op de synchroniseerbare entiteiten (Subject, Family, TimetableSite, TimetableClassroom, TimetableResource, TimetableTeacher, TimetableClass, TimetableClassGroup, User…), koppelt het aan elke entiteit haar identificaties in de systemen van derden, bijvoorbeeld { "auriga": "12345", "aimaira": "67890" }. Dat is het canonieke ankerpunt voor een koppeling in twee richtingen.

3. De lokale kopie school ↔ rooster is een bewuste keuze. Een vak van een klas of een docent van een rooster is een verrijkte kopie, geen levende verwijzing. Een extern register moet dus beslissen op welk niveau het aanhaakt: het schoolregister (duurzame catalogus) of een bepaald rooster (gedateerde planning). De doorwerkingsregels staan in detail in Organisatie van de gegevens.

De configuratie van de synchronisatie staat in config.extsync (SchoolConfigExtsync): systems (geconfigureerde connectoren), sync (richting en entiteiten), export en schedules, plus de koppeltabellen (mappings) per sleutel en per Omniscol-identificatie. Voor programmatische toegang worden de REST-API en de tokens beschreven in API-tokens; de connectoren voor synchronisatie in Externe synchronisatie.

De exacte en volledige vorm van elk veld blijft bepaald door het JSON-referentieschema van het account (https://api.omniscol.com/api/guest/school_schema.json, leesbare weergave op omniscol.com/nl/datamodel). Wijkt deze pagina af van het schema, dan geldt het schema.