Complete data model: JSON entities, relationships and ontology

This page describes the complete data model of an Omniscol account: the entities, their main fields and their relationships. It extends the conceptual page Data organization, which explains the why (school repository ↔ timetable, local copies); here, the goal is the what — an actionable structural map, in particular to map the model to an external repository (management software, directory, information system).

Technical page. This reference is aimed at integration and matching with an external system. It is not required for everyday use of Omniscol: to understand how the data is organized on the business side, see Data organization.

All of a school's data is organized as a tree. The entities described below (users, school years, timetables, absences, events, etc.) correspond to the different branches of this structure. The normative reference is the account's JSON schema. It can be consulted in two forms:

• the raw source (the JSON schema as such), served by the account at https://api.omniscol.com/api/guest/school_schema.json;
• the tree viewer, readable at omniscol.com/en/datamodel (and the corresponding API reference at omniscol.com/en/developers).

This schema describes exactly the physical storage in the database, as a JSON document. This page provides an organized reading of it, stable over time.

The school document: the root

The root document gathers the school's durable repository and all its planning data. Its top-level subtrees:

The subtrees described as "dictionary" are JSON objects whose keys are stable identifiers (the pivot of any external mapping — see the final section).

Cross-cutting fields: _extids and wishes

Two fields appear on many entities. To avoid repeating them in every schema, they are described once here.

• _extids (ExternalIds) — table of the entity's identifiers in external systems, for example { "auriga": "12345" }. Present on synchronizable entities (subjects, families, users, sites, classrooms, resources, teachers, classes, groups…). It is the anchor point for matching with an external repository (see the final section).
• wishes — time constraints: availability, preferred or avoided time slots, maximum hourly volume, preferred classroom… Present on most schedulable entities: users, teachers and subjects of a timetable, groups, classes, classrooms, site hour ranges, staffing grids. Depending on the scope, these constraints are global (school level) or specific to one timetable.

Level 1 — The school repository

The school repository contains what is true for the institution, independently of any timetable: the subject catalog, the user directory, the calendar of school years.

Subjects — SubjectFull / Subject / Family

A custom subject (SubjectFull) extends the base subject (Subject: name, short, code, type, _extids) with parent, family and color. Two origins coexist at the school level: the country's common subjects (read-only) and the school's custom subjects. Functional details: Managing subjects.

Users — User (including teachers)

A User is the single entity of the directory: identity (last name, first name, idnumber, contact), authentication (login), roles, reference service hours (servicehours), global availability (wishes field) and placements. A teacher is not a separate entity: it is a User with teacher among its roles (the same user can hold several roles). The placements field (indexed by school year) attaches a student to a class and to groups over a period. Details: Managing teachers.

School years — SchoolYear / Holiday

A SchoolYear defines date_start → date_end, the list of holidays and the altweeks (alternate weeks). It is a time frame, not a container: timetables unfold within it without being nested in it. See School year.

Level 2 — The timetable

A Timetable is a coherent planning unit. It carries its own local copy of teachers, classes, groups and subjects — see the local-copy principle in Data organization.

Configuration — TimetableConfig

The decisive field is type: week (repeated weekly), cycle (multi-day cycle, see cycle) or calendar (real dates, see dates). time_period and time_unit define the grid's framework; weekdays the working days; date_windows the constraint windows for automatic generation.

Sites, classrooms, resources

A TimetableSite (site) contains its classrooms (TimetableClassroom: capacity, specialisation, maxclasses, building) and its resources (TimetableResource: number = available quantity, for which the system prevents overbooking). distances models travel times between sites. See Sites, classrooms and resources and Classroom specialisations.

Timetable teachers — TimetableTeacher

An enriched partial copy of a User: only a few identifying fields are copied (first_name, last_name, idnumber), plus fields specific to planning (overridable servicehours, preferred classroom, per-timetable wishes). A non-empty virtual_name designates a virtual teacher (a position to fill, with no real User behind it).

Classes, class subjects, groups

• TimetableClass: name, level, campus/sites, studentsnb, and three key subtrees — subjects, groups, courses.
• TimetableClassSubject: local copy of a subject (extends Subject) enriched for planning — minutes (target volume), pweight (pedagogical weight), incompatibilities, default teachers, classroom specialisation. Assigning a subject with a course type creates a separate entry per type. See Courses, lessons, course types.
• TimetableClassGroup: a subset of a class. free=true disables conflicts with the rest of the class (free group); parent establishes the group hierarchy.

Rules between groups — divisions, alignments, groups of groups

The relationships between groups are carried by the timetable's groups subtree, in three forms:

See also the overview Class, group, subgroup.

Level 3 — Lessons

A lesson (Lesson) is the teaching unit actually placed in the timetable: duration, subject, group, teacher(s), classroom, resources, position and status. It is generated from a class subject (see level 2) and attached either to a class (class.courses), or directly to the timetable (timetable.lessons) — the latter case for groups of groups and multi-group lessons spanning several classes.

Core of a lesson

A lesson carries the planning fields — duration (in periods), duration_actual / duration_accounted (actual / billed minutes), modality, subject, group, teachers, classroom, resources — plus its position, its status, its memos and an identity (_id, _osrev). Setting teachers or classroom to null explicitly forces the absence of a teacher or classroom.

Complex lessons

A lesson can group other lessons:

• assoc — associated lessons: the groups swap together.
• concat — concatenated lessons: strictly consecutive.
• weekalt — alternate weeks: one lesson variant per week.

These mechanisms cover complex lessons — see Complex lessons: alternate, associated, concatenated.

Position of a lesson

The position is an object that places the lesson in time. It gathers the following fields:

• position.day — the day of the lesson, polymorphic depending on the timetable mode: a day name (monday…sunday) in weekly mode, a cycle day number ("1", "2"…) in cycle mode, or a YYYY-MM-DD date in calendar mode. It is one and the same field that changes form depending on the mode; it is always present.
• position.period — the slot index in the time grid. A lesson with neither period nor start/end corresponds to a public holiday.
• position.start / position.end — exact start and end times (HH:MM), for off-grid lessons or calendar-mode lessons that do not align with a standard time slot.
• position.fixed — boolean (false by default): a pinned lesson, which automatic generation will not move.

The lessons of a class live in class.courses; the timetable.lessons array carries the cross-class lessons tied to groups of groups.

Identity of a lesson

Each lesson carries two technical identity fields, present on Premium accounts:

• _id — a stable identifier, assigned when the lesson is created and immutable afterwards (it combines a timestamp and a fingerprint of the content). It is the key of a lesson for collaborative editing and for an external tool that tracks lessons over time. For the recurring occurrences of a calendar timetable (alternate weeks, concatenations, associations), the _id of each occurrence is derived from that of the base lesson, which remains recognizable.
• _osrev — a revision token (optimistic locking), incremented on every modification (timestamp + modification index), in a strictly alphabetical order (which makes it easy to tell whether one revision is more recent than another). It lets collaborative editing detect and merge concurrent modifications: an outdated client revision signals a conflict, which the server resolves or merges instead of silently overwriting.

Absences

Absences share a common base (Absence: date_start, date_end, reason, hours, comment, status) specialized per type of absentee.

An AbsenceTeacher can be restricted to certain subjects/classes and carries an array of substitution rules (substitutes, each an AbsenceTeacherSubstitute: substitute, period, time slots, classes and subjects covered). Statuses differ per absentee type (for example ok/aborted for a class). See the glossary entry Substitution / Replacement and the Absence management module.

Staff members

A separate module (also sold standalone) for supervision and staff duty services.

A StaffingGrid is the template (days, periods); the assignments describe the positions (req/ideal, priority, detailed needs per time slot via StaffingNeedSpan); the schedule materializes the actual shifts by date. See the Staffing module.

Events

An Event is an agenda entry laid over the grid: something that happens in the school without being a regular lesson — a class council, a parent-teacher meeting, a one-day exam, a field trip, an open day. Events are stored in the events dictionary (keys event-<n>) and are part of the Premium features.

Fields of an Event (required: title, start, end):

• title — displayed title.
• start / end — start and end, in YYYYMMDDTHHmmSS format.
• rrule — optional recurrence rule.
• attendees — participants: a user, a class, a group, a free-form label (custom), or the whole school (everybody) / anyone willing (anyone).
• location — place(s): a timetable classroom or a free-form label.
• resources — resources booked for the event.
• videolink — video conference link to attend remotely.
• memos — comments; color — color (hexadecimal).

How it works in practice (creation, placement on the grid, interface fields) is described in One-off events.

Display panels

A Panel is a display panel showing the day's lessons (lobby, room, welcome screen…). It defines the selection of columns, the topline, the filters/exclusions and appearance settings. See the glossary entry Display panel.

Identifiers, local copies and mapping to an ERP

To link the Omniscol model to an external repository, three principles come first:

1. Dictionary keys are the stable identifiers. Subjects, users, teachers, classes, groups, classrooms, resources are indexed by an immutable identifier (the JSON key), not by their label. This pivot — never the name — is what must be used for any correspondence.

2. The _extids field (ExternalIds) carries the external identifiers. Present on synchronizable entities (Subject, Family, TimetableSite, TimetableClassroom, TimetableResource, TimetableTeacher, TimetableClass, TimetableClassGroup, User…), it associates each entity with its identifiers in third-party systems, for example { "auriga": "12345", "aimaira": "67890" }. It is the canonical anchor point for a bidirectional mapping.

3. The school ↔ timetable local copy is deliberate. A class subject or a timetable teacher is an enriched copy, not a live reference. An external repository must therefore decide at which level it maps: the school repository (durable catalog) or a specific timetable (dated planning). The detailed propagation rules are in Data organization.

The synchronization configuration lives in config.extsync (SchoolConfigExtsync): systems (configured connectors), sync (direction and entities), export and schedules, plus correspondence tables (mappings) by key and Omniscol identifier. For programmatic access, the REST API and tokens are described in API tokens; the synchronization connectors in External synchronization.

The exact and exhaustive shape of each field remains defined by the account's reference JSON schema (https://api.omniscol.com/api/guest/school_schema.json, readable viewer at omniscol.com/en/datamodel). If this page and the schema diverge, the schema prevails.