Modèle de données complet : entités JSON, relations et ontologie

Cette page décrit le modèle de données complet d'un compte Omniscol : les entités, leurs champs principaux et leurs relations. Elle prolonge la page conceptuelle Organisation des données, qui explique le pourquoi (référentiel école ↔ EDT, copies locales) ; ici, l'objectif est le quoi — une cartographie structurelle exploitable, notamment pour mettre en relation le modèle avec un référentiel externe (progiciel de gestion, annuaire, système d'information).

Page technique. Cette référence s'adresse à l'intégration et à l'appariement avec un système externe. Elle n'est pas nécessaire à l'usage courant d'Omniscol : pour comprendre l'organisation des données côté métier, voir Organisation des données.

Toutes les données d’un établissement sont organisées sous forme d’arbre. Les entités décrites ci-dessous (utilisateurs, années scolaires, emplois du temps, absences, événements, etc.) correspondent aux différentes branches de cette structure. La référence normative est le schéma JSON du compte. Il se consulte sous deux formes :

• la source brute (le schéma JSON tel quel), servie par le compte à l'adresse https://api.omniscol.com/api/guest/school_schema.json ;
• la visionneuse arborescente lisible sur omniscol.com/fr/datamodel (et la référence d'API correspondante sur omniscol.com/fr/developers).

Ce schéma décrit exactement le stockage physique en base, sous forme de document JSON. Cette page en donne une lecture organisée et stable dans le temps.

Le document école : la racine

Le document racine regroupe le référentiel durable de l'établissement et toutes ses planifications. Ses sous-arbres de premier niveau :

Les sous-arbres exprimés comme « dictionnaire » sont des objets JSON dont les clés sont des identifiants stables (le pivot de toute mise en relation externe — voir la section finale).

Champs transversaux : _extids et wishes

Deux champs reviennent sur de nombreuses entités. Pour ne pas les répéter dans chaque schéma, ils sont décrits une seule fois ici.

• _extids (ExternalIds) — table des identifiants de l'entité dans les systèmes externes, par exemple { "auriga": "12345" }. Présent sur les entités synchronisables (matières, familles, utilisateurs, sites, salles, ressources, professeurs, classes, groupes…). C'est le point d'ancrage d'un appariement avec un référentiel externe (voir la section finale).
• wishes — contraintes horaires : disponibilités, créneaux souhaités ou à éviter, volume horaire maximal, salle préférée… Présent sur la plupart des entités planifiables : utilisateurs, professeurs et matières d'un EDT, groupes, classes, salles, plages horaires de site, grilles d'encadrement. Selon le périmètre, ces contraintes sont globales (niveau école) ou propres à un EDT.

Niveau 1 — Le référentiel école

Le référentiel école contient ce qui est vrai pour l'établissement, indépendamment d'un EDT : le catalogue des matières, l'annuaire des utilisateurs, le calendrier des années scolaires.

Matières — SubjectFull / Subject / Family

Une matière personnalisée (SubjectFull) étend la matière de base (Subject : name, short, code, type, _extids) avec parent, family et color. Deux origines coexistent au niveau école : les matières communes au pays (lecture seule) et les matières personnalisées de l'établissement. Détails fonctionnels : Gérer les matières.

Utilisateurs — User (dont les professeurs)

Un User est l'entité unique de l'annuaire : identité (nom, prénom, idnumber, contact), authentification (login), roles, service horaire de référence (servicehours), disponibilités globales (champ wishes) et placements. Un professeur n'est pas une entité distincte : c'est un User ayant teacher parmi ses roles (un même utilisateur peut cumuler plusieurs rôles). Le champ placements (indexé par année scolaire) rattache un élève à une class et à des groups sur une période. Détails : Gérer les professeurs.

Années scolaires — SchoolYear / Holiday

Une SchoolYear définit date_start → date_end, la liste de holidays et les altweeks (semaines alternées). C'est un cadre temporel, pas un conteneur : les EDT s'y déploient sans y être imbriqués. Voir Année scolaire.

Niveau 2 — L'emploi du temps (EDT)

Un Timetable est une unité de planification cohérente. Il porte sa propre copie locale des professeurs, classes, groupes et matières — voir le principe de copie locale dans Organisation des données.

Configuration — TimetableConfig

Le champ déterminant est type : week (hebdomadaire répété), cycle (cycle multi-jours, voir cycle) ou calendar (dates réelles, voir dates). time_period et time_unit définissent la trame de la grille ; weekdays les jours ouvrés ; date_windows les fenêtres de contrainte pour la génération automatique.

Sites, salles, ressources

Un TimetableSite (site) contient ses classrooms (TimetableClassroom : capacity, specialisation, maxclasses, building) et ses resources (TimetableResource : number = quantité disponible, dont le système assure la non-surréservation). distances modélise les temps de trajet inter-sites. Voir Sites, salles et ressources et Spécialisations de salles.

Professeurs de l'EDT — TimetableTeacher

Copie partielle enrichie d'un User : seuls quelques champs identifiants sont recopiés (first_name, last_name, idnumber), auxquels s'ajoutent des champs propres à la planification (servicehours surchargeable, classroom préférée, wishes par EDT). Un virtual_name non vide désigne un professeur virtuel (poste à pourvoir, sans User réel derrière).

Classes, matières de classe, groupes

• TimetableClass : name, level, campus/sites, studentsnb, et trois sous-arbres clés — subjects, groups, courses.
• TimetableClassSubject : copie locale d'une matière (étend Subject) enrichie pour la planification — minutes (volume visé), pweight (poids pédagogique), incompatibilities, teachers par défaut, specialisation de salle. Affecter une matière avec un type de cours crée une entrée distincte par type. Voir Cours, séances, types de cours.
• TimetableClassGroup : un sous-ensemble d'une classe. free=true désactive les conflits avec le reste de la classe (groupe libre) ; parent établit la hiérarchie de groupes.

Règles entre groupes — partitions, alignements, groupes de groupes

Les relations entre groupes sont portées par le sous-arbre groups de l'EDT, sous trois formes :

Voir aussi la vue d'ensemble Classe, groupe, sous-groupe.

Niveau 3 — Les séances de cours

Une séance de cours (Lesson) est l'unité d'enseignement réellement placée dans l'emploi du temps : durée, matière, groupe, professeur(s), salle, ressources, position et statut. Elle est générée à partir d'une matière de classe (voir niveau 2) et rattachée soit à une classe (class.courses), soit directement à l'emploi du temps (timetable.lessons) — ce dernier cas pour les groupes de groupes et les séances multi-groupes, transversales à plusieurs classes.

Cœur d'une séance de cours

Une séance de cours porte les champs de planification — duration (en périodes), duration_actual / duration_accounted (minutes réelles / facturées), modality, subject, group, teachers, classroom, resources — auxquels s'ajoutent sa position, son status, ses memos et une identité (_id, _osrev). Mettre teachers ou classroom à null force explicitement l'absence de professeur ou de salle.

Cours complexes

Une séance peut en regrouper d'autres :

• assoc — séances associées : les groupes permutent ensemble.
• concat — séances concaténées : strictement consécutives.
• weekalt — semaines alternées : une variante de séance par semaine.

Ces mécanismes couvrent les cours complexes — voir Cours complexes : alternées, associées, concaténées.

Position d'une séance

La position est un objet qui place la séance dans le temps. Elle regroupe les champs suivants :

• position.day — le jour de la séance, polymorphe selon le mode de l'EDT : un nom de jour (monday…sunday) en mode hebdomadaire, un numéro de jour de cycle ("1", "2"…) en mode cyclique, ou une date YYYY-MM-DD en mode calendrier. C'est un seul et même champ qui change de forme selon le mode ; il est toujours présent.
• position.period — l'index du créneau dans la grille horaire. Une séance sans period ni start/end correspond à un jour férié.
• position.start / position.end — heures exactes de début et de fin (HH:MM), pour les séances hors grille ou en mode calendrier qui ne s'alignent pas sur un créneau standard.
• position.fixed — booléen (faux par défaut) : une séance punaisée, que la génération automatique ne déplacera pas.

Les séances d'une classe vivent dans class.courses ; le tableau timetable.lessons porte les séances transversales liées aux groupes de groupes.

Identité d'une séance

Chaque séance porte deux champs techniques d'identité, présents sur les comptes Premium :

• _id — identifiant stable, attribué à la création de la séance et immuable ensuite (il combine un horodatage et une empreinte du contenu). C'est la clé d'une séance pour l'édition collaborative et pour un outil externe qui suit les séance dans le temps. Pour les occurrences récurrentes d'un EDT calendrier (semaines alternées, concaténations, associations), l'_id de chaque occurrence est dérivé de celui de la séance de base, qui reste reconnaissable.
• _osrev — jeton de révision (verrouillage optimiste), incrémenté à chaque modification (horodatage + indice de modification), de manière strictement ordonnée alphabétiquement (ce qui permet aisément de savoir si une révision est plus récente qu'une autre). Il permet à l'édition collaborative de détecter et fusionner les modifications concurrentes : une révision client périmée signale un conflit, que le serveur tranche ou fusionne au lieu d'écraser silencieusement.

Absences

Les absences partagent une base commune (Absence : date_start, date_end, reason, hours, comment, statut) déclinée par sujet.

Une AbsenceTeacher peut être restreinte à certaines subjects/classes et porte un tableau de règles de remplacement (substitutes, chacune un AbsenceTeacherSubstitute : remplaçant, période, créneaux horaires, classes et matières couvertes). Les statuts diffèrent par sujet (par exemple ok/aborted pour une classe). Voir le glossaire Remplacement / Suppléance et le module Gestion des absences.

Membres du personnel

Module distinct (vendu aussi en autonome) pour la surveillance et les services d'encadrement.

Une StaffingGrid est le gabarit (jours, périodes) ; les assignments décrivent les postes (req/ideal, priority, needs détaillés par créneau via StaffingNeedSpan) ; le schedule matérialise les vacations effectives par date. Voir le module Service du personnel.

Évènements

Un Event est une entrée d'agenda posée par-dessus la grille : quelque chose qui se passe dans l'établissement sans être un cours régulier — un conseil de classe, une réunion parents-professeurs, un examen sur une journée, une sortie, une journée portes ouvertes. Les évènements sont rangés dans le dictionnaire events (clés event-<n>) et font partie des fonctionnalités Premium.

Champs d'un Event (obligatoires : title, start, end) :

• title — intitulé affiché.
• start / end — début et fin, au format YYYYMMDDTHHmmSS.
• rrule — règle de récurrence éventuelle.
• attendees — participants : un utilisateur, une classe, un groupe, un libellé libre (custom), ou bien tout l'établissement (everybody) / toute personne volontaire (anyone).
• location — lieu(x) : une salle de l'EDT ou un libellé libre.
• resources — ressources réservées pour l'évènement.
• videolink — lien de visioconférence pour y assister à distance.
• memos — commentaires ; color — couleur (hexadécimal).

Le fonctionnement côté usage (création, pose sur la grille, champs de l'interface) est décrit dans Évènements ponctuels.

Panneaux d'affichage

Un Panel est un panneau d'affichage des séances du jour (hall, salle, écran d'accueil…). Il définit la sélection des columns, la topline, les filters/exclusions et des réglages d'apparence. Voir le glossaire Panneau d'affichage.

Identifiants, copies locales et mise en relation avec un ERP

Pour relier le modèle Omniscol à un référentiel externe, trois principes priment :

1. Les clés de dictionnaire sont les identifiants stables. Les matières, utilisateurs, professeurs, classes, groupes, salles, ressources sont indexés par un identifiant immuable (la clé JSON), et non par leur libellé. C'est ce pivot — jamais le name — qu'il faut utiliser pour toute correspondance.

2. Le champ _extids (ExternalIds) porte les identifiants externes. Présent sur les entités synchronisables (Subject, Family, TimetableSite, TimetableClassroom, TimetableResource, TimetableTeacher, TimetableClass, TimetableClassGroup, User…), il associe à chaque entité ses identifiants dans les systèmes tiers, par exemple { "auriga": "12345", "aimaira": "67890" }. C'est le point d'ancrage canonique d'un appariement bidirectionnel.

3. La copie locale école ↔ EDT est volontaire. Une matière de classe ou un professeur d'EDT est une copie enrichie, pas une référence vive. Un référentiel externe doit donc décider à quel niveau il s'apparie : le référentiel école (catalogue durable) ou un EDT précis (planification datée). Le détail des règles de propagation figure dans Organisation des données.

La configuration de synchronisation vit dans config.extsync (SchoolConfigExtsync) : systems (connecteurs configurés), sync (sens et entités), export et schedules, ainsi que des tables de correspondance (mappings) par clé et identifiant Omniscol. Côté accès programmatique, l'API REST et les jetons sont décrits dans Jetons d'API ; les connecteurs de synchronisation dans Synchronisation externe.

La forme exacte et exhaustive de chaque champ reste définie par le schéma JSON de référence du compte (https://api.omniscol.com/api/guest/school_schema.json, visionneuse lisible sur omniscol.com/fr/datamodel). En cas de divergence entre cette page et le schéma, le schéma fait foi.