Modelo de datos completo: entidades JSON, relaciones y ontología

Esta página describe el modelo de datos completo de una cuenta Omniscol: las entidades, sus campos principales y sus relaciones. Prolonga la página conceptual Organización de los datos, que explica el porqué (repositorio escolar ↔ horario, copias locales); aquí, el objetivo es el qué — un mapa estructural aprovechable, en particular para relacionar el modelo con un repositorio externo (software de gestión, directorio, sistema de información).

Página técnica. Esta referencia está dirigida a la integración y al emparejamiento con un sistema externo. No es necesaria para el uso habitual de Omniscol: para comprender la organización de los datos desde el punto de vista de la gestión, consulte Organización de los datos.

Todos los datos de un centro se organizan en forma de árbol. Las entidades descritas a continuación (usuarios, años escolares, horarios, ausencias, eventos, etc.) corresponden a las distintas ramas de esta estructura. La referencia normativa es el esquema JSON de la cuenta. Se consulta en dos formas:

• el origen bruto (el esquema JSON tal cual), servido por la cuenta en la dirección https://api.omniscol.com/api/guest/school_schema.json;
• el visor en árbol legible en omniscol.com/es/datamodel (y la referencia de API correspondiente en omniscol.com/es/developers).

Este esquema describe exactamente el almacenamiento físico en la base de datos, en forma de documento JSON. Esta página ofrece una lectura organizada y estable en el tiempo.

El documento escuela: la raíz

El documento raíz reúne el repositorio duradero del centro y todas sus planificaciones. Sus subárboles de primer nivel:

Los subárboles expresados como «diccionario» son objetos JSON cuyas claves son identificadores estables (el pivote de toda relación externa — véase la sección final).

Campos transversales: _extids y wishes

Dos campos reaparecen en numerosas entidades. Para no repetirlos en cada esquema, se describen una sola vez aquí.

• _extids (ExternalIds) — tabla de los identificadores de la entidad en los sistemas externos, por ejemplo { "auriga": "12345" }. Presente en las entidades sincronizables (asignaturas, familias, usuarios, sitios, aulas, recursos, profesores, clases, grupos…). Es el punto de anclaje de un emparejamiento con un repositorio externo (véase la sección final).
• wishes — restricciones horarias: disponibilidad, franjas horarias deseadas o a evitar, volumen horario máximo, aula preferida… Presente en la mayoría de las entidades planificables: usuarios, profesores y asignaturas de un horario, grupos, clases, aulas, franjas horarias de un sitio, cuadrículas de vigilancia. Según el alcance, estas restricciones son globales (nivel escuela) o propias de un horario.

Nivel 1 — El repositorio escolar

El repositorio escolar contiene lo que es cierto para el centro, independientemente de un horario: el catálogo de asignaturas, el directorio de usuarios, el calendario de los años escolares.

Asignaturas — SubjectFull / Subject / Family

Una asignatura personalizada (SubjectFull) extiende la asignatura de base (Subject: name, short, code, type, _extids) con parent, family y color. Dos orígenes coexisten a nivel escuela: las asignaturas comunes del país (solo lectura) y las asignaturas personalizadas del centro. Detalles funcionales: Gestionar las asignaturas.

Usuarios — User (incluidos los profesores)

Un User es la entidad única del directorio: identidad (apellidos, nombre, idnumber, contacto), autenticación (login), roles, servicio horario de referencia (servicehours), disponibilidad global (campo wishes) y placements. Un profesor no es una entidad distinta: es un User que tiene teacher entre sus roles (un mismo usuario puede acumular varios roles). El campo placements (indexado por año escolar) vincula un estudiante a una class y a unos groups durante un periodo. Detalles: Gestionar los profesores.

Años escolares — SchoolYear / Holiday

Un SchoolYear define date_start → date_end, la lista de holidays y las altweeks (semanas alternas). Es un marco temporal, no un contenedor: los horarios se despliegan en él sin estar anidados. Véase Año escolar.

Nivel 2 — El horario

Un Timetable es una unidad de planificación coherente. Lleva su propia copia local de profesores, clases, grupos y asignaturas — véase el principio de copia local en Organización de los datos.

Configuración — TimetableConfig

El campo determinante es type: week (semanal repetido), cycle (ciclo de varios días, véase cycle) o calendar (fechas reales, véase dates). time_period y time_unit definen la trama de la cuadrícula; weekdays los días laborables; date_windows las ventanas de restricción para la generación automática.

Sitios, aulas, recursos

Un TimetableSite (sitio) contiene sus classrooms (TimetableClassroom: capacity, specialisation, maxclasses, building) y sus resources (TimetableResource: number = cantidad disponible, cuya sobrerreserva el sistema impide). distances modela los tiempos de trayecto entre sitios. Véase Sitios, aulas y recursos y Especializaciones de aulas.

Profesores del horario — TimetableTeacher

Copia parcial enriquecida de un User: solo se copian algunos campos identificadores (first_name, last_name, idnumber), a los que se añaden campos propios de la planificación (servicehours reemplazable, classroom preferida, wishes por horario). Un virtual_name no vacío designa un profesor virtual (un puesto por cubrir, sin un User real detrás).

Clases, asignaturas de clase, grupos

• TimetableClass: name, level, campus/sites, studentsnb, y tres subárboles clave — subjects, groups, courses.
• TimetableClassSubject: copia local de una asignatura (extiende Subject) enriquecida para la planificación — minutes (volumen previsto), pweight (peso pedagógico), incompatibilities, teachers por defecto, specialisation de aula. Asignar una asignatura con un tipo de sesión crea una entrada distinta por tipo. Véase Cursos, sesiones, tipos de sesión.
• TimetableClassGroup: un subconjunto de una clase. free=true desactiva los conflictos con el resto de la clase (grupo libre); parent establece la jerarquía de grupos.

Reglas entre grupos — particiones, alineaciones, grupos de grupos

Las relaciones entre grupos las lleva el subárbol groups del horario, en tres formas:

Véase también la vista de conjunto Clase, grupo, subgrupo.

Nivel 3 — Las sesiones

Una sesión (Lesson) es la unidad de enseñanza realmente colocada en el horario: duración, asignatura, grupo, profesor(es), aula, recursos, posición y estado. Se genera a partir de una asignatura de clase (véase el nivel 2) y se vincula o bien a una clase (class.courses), o bien directamente al horario (timetable.lessons) — este último caso para los grupos de grupos y las sesiones multigrupo, transversales a varias clases.

Núcleo de una sesión

Una sesión lleva los campos de planificación — duration (en periodos), duration_actual / duration_accounted (minutos reales / facturados), modality, subject, group, teachers, classroom, resources — a los que se añaden su position, su status, sus memos y una identidad (_id, _osrev). Poner teachers o classroom en null fuerza explícitamente la ausencia de profesor o de aula.

Sesiones complejas

Una sesión puede agrupar otras:

• assoc — sesiones asociadas: los grupos permutan juntos.
• concat — sesiones concatenadas: estrictamente consecutivas.
• weekalt — semanas alternas: una variante de sesión por semana.

Estos mecanismos cubren las sesiones complejas — véase Sesiones complejas: alternas, asociadas, concatenadas.

Posición de una sesión

La position es un objeto que sitúa la sesión en el tiempo. Reúne los campos siguientes:

• position.day — el día de la sesión, polimorfo según el modo del horario: un nombre de día (monday…sunday) en modo semanal, un número de día de ciclo ("1", "2"…) en modo cíclico, o una fecha YYYY-MM-DD en modo calendario. Es un único y mismo campo que cambia de forma según el modo; siempre está presente.
• position.period — el índice de la franja horaria en la cuadrícula horaria. Una sesión sin period ni start/end corresponde a un día festivo.
• position.start / position.end — horas exactas de inicio y de fin (HH:MM), para las sesiones fuera de cuadrícula o en modo calendario que no se alinean con una franja horaria estándar.
• position.fixed — booleano (falso por defecto): una sesión fijada, que la generación automática no desplazará.

Las sesiones de una clase viven en class.courses; la matriz timetable.lessons lleva las sesiones transversales ligadas a los grupos de grupos.

Identidad de una sesión

Cada sesión lleva dos campos técnicos de identidad, presentes en las cuentas Premium:

• _id — identificador estable, asignado al crear la sesión e inmutable después (combina una marca de tiempo y una huella del contenido). Es la clave de una sesión para la edición colaborativa y para una herramienta externa que sigue las sesiones a lo largo del tiempo. Para las ocurrencias recurrentes de un horario calendario (semanas alternas, concatenaciones, asociaciones), el _id de cada ocurrencia se deriva del de la sesión de base, que sigue siendo reconocible.
• _osrev — token de revisión (bloqueo optimista), incrementado en cada modificación (marca de tiempo + índice de modificación), de manera estrictamente ordenada alfabéticamente (lo que permite saber con facilidad si una revisión es más reciente que otra). Permite a la edición colaborativa detectar y fusionar las modificaciones concurrentes: una revisión de cliente caducada señala un conflicto, que el servidor resuelve o fusiona en lugar de sobrescribir en silencio.

Ausencias

Las ausencias comparten una base común (Absence: date_start, date_end, reason, hours, comment, estado) especializada por tipo de ausente.

Una AbsenceTeacher puede restringirse a ciertas subjects/classes y lleva una matriz de reglas de sustitución (substitutes, cada una un AbsenceTeacherSubstitute: sustituto, periodo, franjas horarias, clases y asignaturas cubiertas). Los estados difieren por tipo de ausente (por ejemplo ok/aborted para una clase). Véase la entrada del glosario Sustitución / Suplencia y el módulo Gestión de ausencias.

Personal

Un módulo distinto (vendido también de forma autónoma) para la vigilancia y los servicios de supervisión.

Una StaffingGrid es la plantilla (días, periodos); los assignments describen los puestos (req/ideal, priority, needs detallados por franja horaria mediante StaffingNeedSpan); el schedule materializa los turnos efectivos por fecha. Véase el módulo Gestión de personal.

Eventos

Un Event es una entrada de agenda superpuesta a la cuadrícula: algo que ocurre en el centro sin ser una sesión regular — una junta de evaluación, una reunión de padres y profesores, un examen de una jornada, una salida, una jornada de puertas abiertas. Los eventos se almacenan en el diccionario events (claves event-<n>) y forman parte de las funcionalidades Premium.

Campos de un Event (obligatorios: title, start, end):

• title — título mostrado.
• start / end — inicio y fin, en formato YYYYMMDDTHHmmSS.
• rrule — regla de recurrencia eventual.
• attendees — participantes: un usuario, una clase, un grupo, una etiqueta libre (custom), o bien todo el centro (everybody) / cualquier persona voluntaria (anyone).
• location — lugar(es): un aula del horario o una etiqueta libre.
• resources — recursos reservados para el evento.
• videolink — enlace de videoconferencia para asistir a distancia.
• memos — comentarios; color — color (hexadecimal).

El funcionamiento en la práctica (creación, colocación en la cuadrícula, campos de la interfaz) se describe en Eventos puntuales.

Paneles de anuncios

Un Panel es un panel de anuncios de las sesiones del día (vestíbulo, sala, pantalla de bienvenida…). Define la selección de columns, la topline, los filters/exclusions y ajustes de apariencia. Véase la entrada del glosario Panel de visualización.

Identificadores, copias locales y relación con un ERP

Para vincular el modelo Omniscol a un repositorio externo, tres principios prevalecen:

1. Las claves de diccionario son los identificadores estables. Las asignaturas, usuarios, profesores, clases, grupos, aulas, recursos se indexan por un identificador inmutable (la clave JSON), y no por su etiqueta. Es este pivote — nunca el name — el que hay que utilizar para toda correspondencia.

2. El campo _extids (ExternalIds) lleva los identificadores externos. Presente en las entidades sincronizables (Subject, Family, TimetableSite, TimetableClassroom, TimetableResource, TimetableTeacher, TimetableClass, TimetableClassGroup, User…), asocia a cada entidad sus identificadores en los sistemas de terceros, por ejemplo { "auriga": "12345", "aimaira": "67890" }. Es el punto de anclaje canónico de un emparejamiento bidireccional.

3. La copia local escuela ↔ horario es voluntaria. Una asignatura de clase o un profesor de horario es una copia enriquecida, no una referencia viva. Un repositorio externo debe, por tanto, decidir a qué nivel se empareja: el repositorio escolar (catálogo duradero) o un horario preciso (planificación fechada). El detalle de las reglas de propagación figura en Organización de los datos.

La configuración de sincronización vive en config.extsync (SchoolConfigExtsync): systems (conectores configurados), sync (sentido y entidades), export y schedules, así como tablas de correspondencia (mappings) por clave e identificador Omniscol. Para el acceso programático, la API REST y los tokens se describen en Tokens de API; los conectores de sincronización en Sincronización externa.

La forma exacta y exhaustiva de cada campo permanece definida por el esquema JSON de referencia de la cuenta (https://api.omniscol.com/api/guest/school_schema.json, visor legible en omniscol.com/es/datamodel). En caso de divergencia entre esta página y el esquema, el esquema prevalece.