Modelo de dados completo: entidades JSON, relações e ontologia

Esta página descreve o modelo de dados completo de uma conta Omniscol: as entidades, os seus campos principais e as suas relações. Ela prolonga a página conceitual Organização dos dados, que explica o porquê (referencial da escola ↔ horário, cópias locais); aqui, o objetivo é o quê — um mapa estrutural utilizável, em particular para relacionar o modelo com um referencial externo (software de gestão, diretório, sistema de informação).

Página técnica. Esta referência destina-se à integração e ao emparelhamento com um sistema externo. Ela não é necessária ao uso corrente do Omniscol: para compreender a organização dos dados no lado funcional, ver Organização dos dados.

Todos os dados de um estabelecimento são organizados em forma de árvore. As entidades descritas abaixo (utilizadores, anos letivos, horários, ausências, eventos, etc.) correspondem aos diferentes ramos desta estrutura. A referência normativa é o schema JSON da conta. Ele consulta-se sob duas formas:

• a fonte bruta (o schema JSON tal como é), servida pela conta no endereço https://api.omniscol.com/api/guest/school_schema.json;
• o visualizador em árvore legível em omniscol.com/pt/datamodel (e a referência de API correspondente em omniscol.com/pt/developers).

Este schema descreve exatamente o armazenamento físico na base, em forma de documento JSON. Esta página fornece uma leitura organizada e estável ao longo do tempo.

O documento escola: a raiz

O documento raiz reúne o referencial duradouro do estabelecimento e todas as suas planificações. Os seus subarvores de primeiro nível:

Os subarvores expressos como «dicionário» são objetos JSON cujas chaves são identificadores estáveis (o pivô de todo o mapeamento externo — ver a seção final).

Campos transversais: _extids e wishes

Dois campos surgem em numerosas entidades. Para não os repetir em cada schema, eles são descritos uma única vez aqui.

• _extids (ExternalIds) — tabela dos identificadores da entidade nos sistemas externos, por exemplo { "auriga": "12345" }. Presente nas entidades sincronizáveis (matérias, famílias, utilizadores, campi, salas, recursos, professores, turmas, grupos…). É o ponto de ancoragem de um emparelhamento com um referencial externo (ver a seção final).
• wishes — restrições horárias: disponibilidades, faixas horárias desejadas ou a evitar, volume horário máximo, sala preferida… Presente na maioria das entidades planificáveis: utilizadores, professores e matérias de um horário, grupos, turmas, salas, faixas horárias de campus, grades de vigilância. Conforme o perímetro, estas restrições são globais (nível escola) ou próprias de um horário.

Nível 1 — O referencial escola

O referencial escola contém o que é verdadeiro para o estabelecimento, independentemente de um horário: o catálogo das matérias, o diretório dos utilizadores, o calendário dos anos letivos.

Matérias — SubjectFull / Subject / Family

Uma matéria personalizada (SubjectFull) estende a matéria de base (Subject: name, short, code, type, _extids) com parent, family e color. Duas origens coexistem ao nível escola: as matérias comuns ao país (somente leitura) e as matérias personalizadas do estabelecimento. Detalhes funcionais: Gerir as disciplinas.

Utilizadores — User (incluindo os professores)

Um User é a entidade única do diretório: identidade (nome, apelido, idnumber, contacto), autenticação (login), roles, carga horária de referência (servicehours), disponibilidades globais (campo wishes) e placements. Um professor não é uma entidade distinta: é um User que tem teacher entre os seus roles (um mesmo utilizador pode acumular vários papéis). O campo placements (indexado por ano letivo) vincula um aluno a uma class e a groups durante um período. Detalhes: Gerir os professores.

Anos letivos — SchoolYear / Holiday

Um SchoolYear define date_start → date_end, a lista de holidays e as altweeks (semanas alternadas). É um quadro temporal, não um contêiner: os horários desdobram-se dentro dele sem estarem nele aninhados. Ver Ano letivo.

Nível 2 — O horário

Um Timetable é uma unidade de planificação coerente. Ele carrega a sua própria cópia local dos professores, turmas, grupos e matérias — ver o princípio de cópia local em Organização dos dados.

Configuração — TimetableConfig

O campo determinante é type: week (semanal repetido), cycle (ciclo multidia, ver cycle) ou calendar (datas reais, ver dates). time_period e time_unit definem a trama da grade; weekdays os dias úteis; date_windows as janelas de restrição para a geração automática.

Campi, salas, recursos

Um TimetableSite (campus) contém as suas classrooms (TimetableClassroom: capacity, specialisation, maxclasses, building) e os seus resources (TimetableResource: number = quantidade disponível, cuja não-sobrerreserva o sistema garante). distances modela os tempos de deslocamento entre campi. Ver Campi, salas e recursos e Especializações de salas de aula.

Professores do horário — TimetableTeacher

Cópia parcial enriquecida de um User: apenas alguns campos identificadores são recopiados (first_name, last_name, idnumber), aos quais se juntam campos próprios da planificação (servicehours sobrescrevível, classroom preferida, wishes por horário). Um virtual_name não vazio designa um professor virtual (posto a preencher, sem User real por detrás).

Turmas, matérias de turma, grupos

• TimetableClass: name, level, campus/sites, studentsnb, e três subarvores-chave — subjects, groups, courses.
• TimetableClassSubject: cópia local de uma matéria (estende Subject) enriquecida para a planificação — minutes (volume visado), pweight (peso pedagógico), incompatibilities, teachers por defeito, specialisation de sala. Atribuir uma matéria com um tipo de aula cria uma entrada distinta por tipo. Ver Cursos, aulas, tipos de aula.
• TimetableClassGroup: um subconjunto de uma turma. free=true desativa os conflitos com o resto da turma (grupo livre); parent estabelece a hierarquia de grupos.

Regras entre grupos — divisões, alinhamentos, grupos de grupos

As relações entre grupos são portadas pelo subarvore groups do horário, sob três formas:

Ver também a visão geral Turma, grupo, subgrupo.

Nível 3 — As aulas

Uma aula (Lesson) é a unidade de ensino realmente colocada no horário: duração, matéria, grupo, professor(es), sala, recursos, posição e estado. Ela é gerada a partir de uma matéria de turma (ver nível 2) e vinculada quer a uma turma (class.courses), quer diretamente ao horário (timetable.lessons) — este último caso para os grupos de grupos e as aulas multigrupo, transversais a várias turmas.

Núcleo de uma aula

Uma aula contém os campos de planificação — duration (em períodos), duration_actual / duration_accounted (minutos reais / faturados), modality, subject, group, teachers, classroom, resources — aos quais se juntam a sua position, o seu status, os seus memos e uma identidade (_id, _osrev). Colocar teachers ou classroom em null força explicitamente a ausência de professor ou de sala.

Aulas complexas

Uma aula pode reagrupar outras:

• assoc — aulas associadas: os grupos permutam juntos.
• concat — aulas concatenadas: estritamente consecutivas.
• weekalt — semanas alternadas: uma variante de aula por semana.

Estes mecanismos cobrem as aulas complexas — ver Aulas complexas: alternadas, associadas, concatenadas.

Posição de uma aula

A position é um objeto que coloca a aula no tempo. Ela reúne os seguintes campos:

• position.day — o dia da aula, polimorfo conforme o modo do horário: um nome de dia (monday…sunday) em modo semanal, um número de dia de ciclo ("1", "2"…) em modo cíclico, ou uma data YYYY-MM-DD em modo calendário. É um único e mesmo campo que muda de forma conforme o modo; está sempre presente.
• position.period — o índice da faixa horária na grade horária. Uma aula sem period nem start/end corresponde a um feriado.
• position.start / position.end — horas exatas de início e de fim (HH:MM), para as aulas fora da grade ou em modo calendário que não se alinham com uma faixa horária padrão.
• position.fixed — booleano (falso por defeito): uma aula fixada, que a geração automática não deslocará.

As aulas de uma turma vivem em class.courses; a tabela timetable.lessons contém as aulas transversais ligadas aos grupos de grupos.

Identidade de uma aula

Cada aula contém dois campos técnicos de identidade, presentes nas contas Premium:

• _id — identificador estável, atribuído na criação da aula e imutável em seguida (ele combina um carimbo de data/hora e uma impressão do conteúdo). É a chave de uma aula para a edição colaborativa e para uma ferramenta externa que acompanha as aulas ao longo do tempo. Para as ocorrências recorrentes de um horário calendário (semanas alternadas, concatenações, associações), o _id de cada ocorrência é derivado do da aula de base, que permanece reconhecível.
• _osrev — token de revisão (bloqueio otimista), incrementado a cada modificação (carimbo de data/hora + índice de modificação), de maneira estritamente ordenada alfabeticamente (o que permite facilmente saber se uma revisão é mais recente do que outra). Ele permite à edição colaborativa detectar e fundir as modificações concorrentes: uma revisão de cliente desatualizada sinaliza um conflito, que o servidor resolve ou funde em vez de sobrescrever silenciosamente.

Ausências

As ausências partilham uma base comum (Absence: date_start, date_end, reason, hours, comment, estado) especializada por tipo.

Uma AbsenceTeacher pode ser restringida a certas subjects/classes e contém um conjunto de regras de substituição (substitutes, cada uma um AbsenceTeacherSubstitute: substituto, período, faixas horárias, turmas e matérias cobertas). Os estados diferem consoante o tipo (por exemplo ok/aborted para uma turma). Ver o glossário Substituição / Reposição e o módulo Gestão de ausências.

Membros do pessoal

Módulo distinto (vendido também de forma autônoma) para a vigilância e os serviços de acompanhamento.

Uma StaffingGrid é o gabarito (dias, períodos); os assignments descrevem os postos (req/ideal, priority, needs detalhados por faixa horária via StaffingNeedSpan); o schedule materializa os turnos efetivos por data. Ver o módulo Gestão de pessoal.

Eventos

Um Event é uma entrada de agenda posta por cima da grade: algo que acontece no estabelecimento sem ser uma aula regular — um conselho de turma, uma reunião de pais e professores, um exame de um dia, uma saída, um dia de portas abertas. Os eventos são arrumados no dicionário events (chaves event-<n>) e fazem parte das funcionalidades Premium.

Campos de um Event (obrigatórios: title, start, end):

• title — título exibido.
• start / end — início e fim, no formato YYYYMMDDTHHmmSS.
• rrule — regra de recorrência eventual.
• attendees — participantes: um utilizador, uma turma, um grupo, um rótulo livre (custom), ou então todo o estabelecimento (everybody) / toda pessoa voluntária (anyone).
• location — local(is): uma sala do horário ou um rótulo livre.
• resources — recursos reservados para o evento.
• videolink — link de videoconferência para assistir à distância.
• memos — comentários; color — cor (hexadecimal).

O funcionamento no lado do uso (criação, colocação na grade, campos da interface) é descrito em Eventos pontuais.

Painéis de exibição

Um Panel é um painel de exibição das aulas do dia (hall, sala, ecrã de acolhimento…). Ele define a seleção das columns, a topline, os filters/exclusions e configurações de aparência. Ver o glossário Painel de display.

Identificadores, cópias locais e mapeamento para um ERP

Para ligar o modelo Omniscol a um referencial externo, três princípios prevalecem:

1. As chaves de dicionário são os identificadores estáveis. As matérias, utilizadores, professores, turmas, grupos, salas, recursos são indexados por um identificador imutável (a chave JSON), e não pelo seu rótulo. É esse pivô — nunca o name — que se deve utilizar para toda a correspondência.

2. O campo _extids (ExternalIds) contém os identificadores externos. Presente nas entidades sincronizáveis (Subject, Family, TimetableSite, TimetableClassroom, TimetableResource, TimetableTeacher, TimetableClass, TimetableClassGroup, User…), ele associa a cada entidade os seus identificadores nos sistemas de terceiros, por exemplo { "auriga": "12345", "aimaira": "67890" }. É o ponto de ancoragem canônico de um emparelhamento bidirecional.

3. A cópia local escola ↔ horário é deliberada. Uma matéria de turma ou um professor de horário é uma cópia enriquecida, não uma referência viva. Um referencial externo deve, portanto, decidir a que nível ele se emparelha: o referencial escola (catálogo duradouro) ou um horário preciso (planificação datada). O detalhe das regras de propagação figura em Organização dos dados.

A configuração de sincronização vive em config.extsync (SchoolConfigExtsync): systems (conectores configurados), sync (sentido e entidades), export e schedules, bem como tabelas de correspondência (mappings) por chave e identificador Omniscol. No lado do acesso programático, a API REST e os tokens são descritos em Tokens de API; os conectores de sincronização em Sincronização externa.

A forma exata e exaustiva de cada campo permanece definida pelo schema JSON de referência da conta (https://api.omniscol.com/api/guest/school_schema.json, visualizador legível em omniscol.com/pt/datamodel). Em caso de divergência entre esta página e o schema, o schema prevalece.