OpenT8-Spezifikation¶

Version 0.8.0¶

Die Schlüsselwörter "MUSS/MÜSSEN" (Englisch: "MUST"), "ERFORDERLICH" (Englisch: "REQUIRED"), "EMPFOHLEN" (Englisch: "RECOMMENDED"), "SOLLTE" (Englisch: "SHOULD"), "SOLLTE NICHT" (Englisch: "SHOULD NOT") und "KANN" (Englisch: "MAY") in diesem Dokument sind so zu interpretieren, wie sie in ihrer englischen Übersetzung in RFC2119 und RFC8174 spezifiziert sind, und nur dann, wenn sie, wie hier, in Großbuchstaben geschrieben sind.

Diese Spezifikation ist lizenziert unter der Apache License, Version 2.0.

Einführung¶

OpenT8 definiert ein Standard-Datenformat zur Repräsentation von Stundenplandaten, unabhängig von ihrer Herkunft. Basierend auf dem JSON-Standard kann dieses Format mit nahezu jeder Programmiersprache leicht erzeugt und gelesen werden. Mit Hilfe des OpenT8 Document Schema können Dokumente im OpenT8-Format auf ihre syntaktische Korrektheit hin validiert werden.

OpenT8 kann zum Austausch von Stundenplandaten zwischen Diensten oder Anwendungen genutzt werden, als Quelle für die grafische Anzeige von Stundenplänen oder als Antwortformat für API-Anfragen (z.B. für RESTful Web-Services).

Definitionen¶

OpenT8-Dokument¶

Ein OpenT8-Dokument ist eine in sich geschlossene Ressource, die einen Stundenplan oder Dienstplan definiert und beschreibt. Es MÜSSEN mindestens die Felder opent8, info und schedule enthalten sein. Ein OpenT8-Dokument basiert auf der OpenT8-Spezifikation und ist mit ihr konform.

Personen¶

Personen (Englisch: person) sind Mitglieder (Englisch: member) bzw. Teilnehmer (Englisch: attendee), die Gruppen, Kursen, Veranstaltungen, Aktivitäten, Aufsichten oder Ereignissen zugeordnet werden. Die Art der Mitgliedschaft bzw. Teilnahme wird dabei jeweils durch ihre Rolle (Englisch: role) unterschieden (z.B. Lehrer:in, Erzieher:in, Schüler:in, etc.).

Hier ein Beispiel für die Kursteilnahme eines Lehrers:

"persons": [
  {
    "id": "Leo",
    "name": {
      "shortName": "Leo",
      "familyName": "von Schnitzewitz",
      "middleNames": [
        "Leopold"
      ],
      "givenName": "Alexander",
      "title": "Dr."
    },
    "birthdate": "1969-07-20"
  }
],
"personRoles": [
  {
    "id": "LER",
    "shortName": "LER",
    "longName": "Lehrer:in",
    "code": {
      "codeListRef": {
        "canonicalUri": "urn:opene8:school:codelist:de:personRole",
        "locationUrls": [
          "https://api.codelisthub.org/v1/documents/urn%3Aopene8%3Aschool%3Acodelist%3Ade%3ApersonRole"
        ]
      },
      "keyId": "key",
      "value": "LER"
    }
  }
],
"courses": [
  {
    "id": "DE-1A",
    "shortName": "DE",
    "longName": "Deutsch",
    "subject": {
      "refId": "DE"
    },
    "groups": [
      {
        "refId": "10a"
      }
    ],
    "attendees": [
      {
        "refId": "Leo",
        "role": {
          "refId": "LER"
        }
      }
    ]
  }
]

Gruppen¶

Gruppen (Englisch: group) sind organisatorische Einheiten für Teilnehmer. Sie repräsentieren beispielsweise Klassen, Jahrgänge, Betreuungsgruppen und können durch Gruppentypen kategorisiert werden.

Hier ein Beispiel für zwei Klassen der zehnten Jahrgangsstufe:

"groups": [
  {
    "id": "10a",
    "shortName": "10a",
    "longName": "Klasse 10a",
    "groupType": {
      "refId": "KL"
    }
  },
  {
    "id": "10b",
    "shortName": "10b",
    "longName": "Klasse 10b",
    "groupType": {
      "refId": "KL"
    }
  }
],
"groupTypes": [
  {
    "id": "KL",
    "shortName": "KL",
    "longName": "Klasse",
    "code": {
      "codeListRef": {
        "canonicalUri": "urn:opene8:school:codelist:de:groupType",
        "locationUrls": [
            "https://api.codelisthub.org/v1/documents/urn%3Aopene8%3Aschool%3Acodelist%3Ade%3AgroupType"
          ]
      },
      "keyId": "key",
      "value": "KLA"
    }
  }
]

Kurse¶

Ein Kurs (Englisch: course) besteht in der Regel aus einer Serie von Veranstaltungen zu einem bestimmten Fach (Englisch: subject). Einem Kurs können Teilnehmer (z.B. Lehrer:innen, Schüler:innen etc.) und Gruppen (z.B. Klassen, Jahrgänge, etc.) zugeordnet werden.

Hier ein Beispiel für einen Kurs:

"courses": [
  {
    "id": "DE-1A",
    "shortName": "DE",
    "longName": "Deutsch",
    "subject": {
      "refId": "DE"
    },
    "groups": [
      {
        "refId": "1a"
      }
    ],
    "attendees": [
      {
        "refId": "Leo",
        "role": {
          "refId": "LEHR"
        }
      }
    ]
  }
]

Planelemente¶

Planelemente (Englisch: schedule element) sind die zentralen Objekte, um die sich alles andere gruppiert. Planelemente sind mit Hilfe von zeitlichen Ausdrücken verplant und repräsentieren die sichtbaren Einträge in einem Stundenplan.

Planelemente sind unterschiedlich ausgeprägt.

Veranstaltungen¶

Veranstaltungen bzw. Unterrichtseinheiten (Englisch: lesson) repräsentieren den eigentlichen Unterricht. Eine Veranstaltung MUSS immer mit einem Kurs verknüpft sein. Veranstaltungen umfassen nicht nur ursprünglich geplante Veranstaltungen sondern auch aktuelle Vertretungen (in diesem Fall gibt es eine korrespondierende Fehlstelle mit Verweis auf diese Veranstaltung).

Hier ein Beispiel für die Veranstaltungen eines Musikkurses. Dieser findet jede Woche am Mittwoch und am Donnerstag zu jeweils unterschiedlichen Unterrichtszeiten statt:

"scheduleElements": [
  {
    "type": "lesson",
    "id": "MU-1A",
    "course": {
      "refId": "MU-1A"
    },
    "rooms": [
      {
        "refId": "200"
      }
    ],
    "temporalExpressions": [
      {
        "type": "weekly",
        "startTimepoint": "2023-09-06T11:00:00+02:00",
        "endTimepoint": "2023-09-06T11:45:00+02:00"
      },
      {
        "type": "weekly",
        "startTimepoint": "2023-09-07T12:20:00+02:00",
        "endTimepoint": "2023-09-07T13:05:00+02:00"
      }
    ]
  }
]

Veranstaltungen haben ein optionales Feld classification, mit dem deren Bedeutung festgelegt werden kann. Folgende Werte sind möglich:

scheduled: Das ist der Standardwert, wenn das Feld nicht definiert ist. Er kennzeichnet eine klassisch verplante Veranstaltung.
additional: Dieser Wert soll Veranstaltungen kennzeichnen, die kurzfristig (z.B. im Rahmen der Änderungsplanung) hinzugefügt wurden. Es handelt sich dabei um keinen Vertretungsunterricht sondern vielmehr um einen Zusatzunterricht.
substitution: Dieser Wert soll Veranstaltungen kennzeichnen, die durch die Vertretungsplanung entstanden sind. Sie ersetzen eine andere Veranstaltung, sei es geplant (also scheduled), zusätzlich (also additional) oder ebenfalls vertreten (also substitution).

Aufsichten¶

Aufsichten (Englisch: supervision) repräsentieren Zeiten zwischen Unterricht (z.B. in der Pause). Aufsichten umfassen nicht nur ursprünglich geplante Aufsichten sondern auch aktuelle Aufsichtsvertretungen (in diesem Fall gibt es eine korrespondierende Fehlstelle mit Verweis auf diese Aufsicht).

Hier ein Beispiel für eine Pausenhofaufsicht (montags, mittwochs und freitags, zwei Wochen lang):

"scheduleElements": [
  {
    "type": "supervision",
    "id": "aufsicht-1",
    "notes": "Pausenaufsicht",
    "attendees": [
      {
        "refId": "Leo",
        "role": {
          "refId": "ERZ"
        }
      }
    ],
    "areas": [
      {
        "refId": "Hof"
      }
    ],
    "temporalExpressions": [
      {
        "type": "weekly",
        "startTimepoint": "2023-09-04T08:45:00+02:00",
        "endTimepoint": "2023-09-04T09:05:00+02:00",
        "validFrom": "2023-09-04",
        "validTo": "2023-09-16"
      },
      {
        "type": "weekly",
        "startTimepoint": "2023-09-06T08:45:00+02:00",
        "endTimepoint": "2023-09-06T09:05:00+02:00",
        "validFrom": "2023-09-04",
        "validTo": "2023-09-16"
      },
      {
        "type": "weekly",
        "startTimepoint": "2023-09-08T08:45:00+02:00",
        "endTimepoint": "2023-09-08T09:05:00+02:00",
        "validFrom": "2023-09-04",
        "validTo": "2023-09-16"
      }
    ]
  }
]

Aufsichten haben ein optionales Feld classification, mit dem deren Bedeutung festgelegt werden kann. Folgende Werte sind möglich:

scheduled: Das ist der Standardwert, wenn das Feld nicht definiert ist. Er kennzeichnet eine klassisch verplante Aufsicht.
additional: Dieser Wert soll Aufsichten kennzeichnen, die kurzfristig (z.B. im Rahmen von größeren Schulveranstaltungen) hinzugefügt wurden und somit gesondert visualisiert werden.
substitution: Dieser Wert soll Aufsichten kennzeichnen, die durch die Vertretungsplanung entstanden sind. Sie ersetzen eine andere Aufsicht, sei es geplant (also scheduled) oder ebenfalls vertreten (also substitution).

Aktivitäten¶

Aktivitäten (Englisch: activity) repräsentieren Dienstzeiten, die keine klassischen Lehrveranstaltungen sind (z.B. Bereitschaftsdienst, Hortaufsicht, etc.).

Hier ein Beispiel für eine Hortaufsicht:

"scheduleElements": [
  {
    "type": "activity",
    "id": "ho-1",
    "shortName": "HoAmAbend",
    "longName": "Hortaufsicht am Abend",
    "activityType": {
      "refId": "HA"
    },
    "attendees": [
      {
        "refId": "Eli",
        "role": {
          "refId": "ERZ"
        }
      }
    ],
    "rooms": [
      {
        "refId": "200"
      }
    ],
    "temporalExpressions": [
      {
        "type": "onetime",
        "startTimepoint": "2023-09-01T16:00:00+02:00",
        "endTimepoint": "2023-09-01T18:00:00+02:00"
      }
    ]
  }
],
"activityTypes": [
  {
    "id": "HA",
    "shortName": "HA",
    "longName": "Hortaufsicht"
  }
]

Aktivitäten haben ein optionales Feld classification, mit dem deren Bedeutung festgelegt werden kann. Folgende Werte sind möglich:

scheduled: Das ist der Standardwert, wenn das Feld nicht definiert ist. Er kennzeichnet eine klassisch verplante Aktivität.
additional: Dieser Wert soll Aktivitäten kennzeichnen, die kurzfristig (z.B. im Rahmen von größeren Schulveranstaltungen) hinzugefügt wurden und somit gesondert visualisiert werden.
substitution: Dieser Wert soll Aktivitäten kennzeichnen, die durch die Vertretungsplanung entstanden sind. Sie ersetzen eine andere Aktivität, sei es geplant (also scheduled) oder ebenfalls vertreten (also substitution).

Ereignisse¶

Ereignisse (Englisch: event) sind Termine, die nicht durch Veranstaltungen, Aktivitäten oder Aufsichten repräsentiert werden können (z.B. Meetings, Prüfungen, etc.). Ereignisse können nicht vertreten werden.

Hier ein Beispiel für ein Meeting:

"scheduleElements": [
  {
    "type": "event",
    "id": "meet-1",
    "shortName": "Meeting",
    "longName": "Abstimmung zur Einschulung",
    "eventType": {
      "refId": "KONFI"
    },
    "attendees": [
      {
        "refId": "Max",
        "role": {
          "refId": "LEH"
        }
      },
      {
        "refId": "Eli",
        "role": {
          "refId": "LEH"
        }
      }
    ],
    "rooms": [
      {
        "refId": "LeZi"
      }
    ],
    "temporalExpressions": [
      {
        "type": "onetime",
        "startTimepoint": "2023-09-01T08:00:00+02:00",
        "endTimepoint": "2023-09-01T10:00:00+02:00"
      }
    ]
  }
],
"eventTypes": [
  {
    "id": "KONFI",
    "shortName": "KONFI",
    "longName": "Konferenz"
  }
]

Ferien und Feiertage¶

Ferien bzw. Feiertage (Englisch: holiday) repräsentieren Tage, an denen kein Unterricht stattfindet.

Hier die Weihnachtsferien 2023/2024 als Beispiel:

"scheduleElements": [
  {
    "type": "holiday",
    "id": "WeiFe",
    "shortName": "WeiFe",
    "longName": "Weihnachtsferien",
    "holidayType": "school",
    "temporalExpressions": [
      {
        "type": "onetime",
        "startTimepoint": "2023-12-23T00:00:00+01:00",
        "endTimepoint": "2024-01-05T00:00:00+01:00"
      }
    ]
  }
]

Mitteilungen¶

Mitteilungen (Englisch: announcement) erlauben die Anzeige von zusätzlichen Informationen direkt im Stundenplan.

Hier ein Beispiel für einen Hinweis zum Feueralarm:

"scheduleElements": [
  {
    "type": "announcement",
    "id": "alarm-1",
    "shortDescription": "alarm",
    "longDescription": "Feueralarmübung",
    "notes": "Feueralarmübung am Morgen",
    "color": "#E55604",
    "temporalExpressions": [
      {
        "type": "onetime",
        "startTimepoint": "2023-12-22T08:00:00+01:00",
        "endTimepoint": "2023-12-22T08:25:00+01:00"
      }
    ]
  }
]

Fehlstellen¶

Fehlstellen (Englisch: gap) repräsentieren Veranstaltungen, Aufsichten oder Aktivitäten, die nicht wie geplant stattfinden können. Eine Fehlstelle definiert neben der Zeit die Gründe (Englisch: reason) für die Planänderung (z.B. Lehrer fehlt/ist freigestellt oder Raum ist nicht verfügbar) und die Auflösung (Englisch: resolution). Die Auflösung kann entweder eine Vertretung bzw. ein Ersatz (Englisch: substitution) oder der Ausfall (Englisch: cancellation) sein.

Hier ein Beispiel für einen Lehrerausfall. Der Unterricht wird durch einen Erzieher vertreten:

"scheduleElements": [
  {
    "type": "gap",
    "id": "G-1",
    "notes": "Das ist eine Fehlstelle",
    "appliesTo": {
      "refType": "lesson",
      "refId": "DE-1A"
    },
    "reasons": [
      {
        "type": "absence",
        "notes": "Lehrer ist krank",
        "appliesTo": {
          "refType": "person",
          "refId": "Max"
        }
      }
    ],
    "resolutions": [
      {
        "type": "substitution",
        "notes": "Der Erzieher springt ein",
        "realizedBy": {
          "refType": "lesson",
          "refId": "V-1"
        }
      }
    ],
    "temporalExpressions": [
      {
        "type": "onetime",
        "startTimepoint": "2023-09-04T08:00:00+02:00",
        "endTimepoint": "2023-09-04T08:45:00+02:00"
      }
    ]
  },
  {
    "type": "lesson",
    "id": "V-1",
    "course": {
      "refId": "DE-1A"
    },
    "notes": "Das ist eine Vertretung",
    "classification": "substitution",
    "attendees": [
      {
        "refId": "Leo",
        "role": {
          "refId": "EZ"
        }
      }
    ],
    "rooms": [
      {
        "refId": "102"
      }
    ],
    "temporalExpressions": [
      {
        "type": "onetime",
        "startTimepoint": "2023-09-04T08:00:00+02:00",
        "endTimepoint": "2023-09-04T08:45:00+02:00"
      }
    ]
  }
]

Räume, Gebäude, Campus und Aufsichtsbereiche¶

Planelemente können mit Standorten verknüpft werden. Für Veranstaltungen, Aktivitäten und Ereignisse sind dies Räume (Englisch: room), für Aufsichten sind dies Aufsichtsbereiche (Englisch: supervision area). Räume können für ein Gebäude (Englisch: building) zusammengefasst, Gebäude wiederum für einen Campus (Englisch: campus) zusammengefasst werden. Auch Aufsichtsbereiche können für einen Campus zusammengefasst werden.

Hier ein Beispiel für zwei Räume mit Verweis auf das gleiche Gebäude:

"rooms": [
  {
    "id": "100",
    "shortName": "100",
    "longName": "Raum 100",
    "building": {
      "refId": "HG"
    }
  },
  {
    "id": "101",
    "shortName": "101",
    "longName": "Raum 101",
    "building": {
      "refId": "HG"
    }
  }
]

Zeitliche Ausdrücke¶

Zeitliche Ausdrücke (Englisch: temporal expression) erlauben eine flexible zeitliche Planung von Planelementen.

Die folgenden zeitlichen Ausdrücke werden unterstützt:

Einmalig¶

Einmalige (Englisch: one time) Ausdrücke repräsentieren einen einmaligen Termin, definiert durch einen Startzeitpunkt und einen Endzeitpunkt. Ein einmaliger Termin kann auch mehrtägig sein (z.B. Sommerferien).

Hier ein Beispiel für einen einmaligen Termin.

"temporalExpressions": [
  {
    "type": "onetime",
    "startTimepoint": "2023-09-04T08:00:00+02:00",
    "endTimepoint": "2023-09-04T08:45:00+02:00"
  }
]

Wöchentlich¶

Wöchentliche (Englisch: weekly) Ausdrücke repräsentieren sich wöchentlich wiederholende Termine. Sie werden durch eine Referenzveranstaltung mit einem absoluten Start- und Endzeitpunkt definiert. Aus dieser werden der lokale Wochentag und die lokalen Uhrzeiten in der Zeitzone des Stundenplans abgeleitet. Die Referenzveranstaltung kann außerhalb des Gültigkeitszeitraums liegen.

Standardmäßig findet die Wiederholung in jeder Woche innerhalb des Gültigkeitszeitraums statt. Über die optionale Eigenschaft validWeeks können einzelne ISO-Kalenderwochen ausgewählt werden, beispielsweise für einen 14-tägigen Wechsel oder andere Wochenmuster.

Hier ein Beispiel für einen wöchentlichen Termin, der jedoch nur in bestimmten Kalenderwochen stattfindet:

"temporalExpressions": [
  {
    "type": "weekly",
    "startTimepoint": "2023-09-08T11:00:00+02:00",
    "endTimepoint": "2023-09-08T11:45:00+02:00",
    "validWeeks": [
      "2023:36,38,40,42,44,46,48,50",
      "2024:1-4"
    ]
  }
]

Wochenmuster können auch separat als weeksPattern-Entitäten gespeichert werden, auf die dann referiert werden kann. Auch hierfür ein Beispiel:

"temporalExpressions": [
  {
    "type": "weekly",
    "startTimepoint": "2023-09-08T11:00:00+02:00",
    "endTimepoint": "2023-09-08T11:45:00+02:00",
    "validWeeks": {
      "refId": "A-Woche"
    }
  }
]

Kombination¶

Zeitliche Ausdrücke können miteinander kombiniert und sowohl positiv (findet statt) als auch negativ (findet nicht statt) definiert werden. Die Kombination aus positiven und negativen zeitlichen Ausdrücken erlaubt die Repräsentation von zeitlichen Ausnahmen (z.B. Immer freitags von 11:00 bis 11:45, nur nicht im Juli und im August).

Hier ein Beispiel für einen zeitlichen Ausdruck, bestehend aus einem wöchentlichen Termin, der jedoch an einem bestimmten Tag nicht stattfindet:

"temporalExpressions": [
  {
    "type": "weekly",
    "startTimepoint": "2023-09-08T11:00:00+02:00",
    "endTimepoint": "2023-09-08T11:45:00+02:00",
    "operation": "include"
  },
  {
    "type": "onetime",
    "startTimepoint": "2023-09-22T00:00:00+02:00",
    "endTimepoint": "2023-09-23T00:00:00+02:00",
    "operation": "exclude"
  }
]

Zeitrahmen¶

Planelemente werden u.a. durch konkrete Uhrzeiten definiert. Ein Zeitrahmen (Englisch: time frame) erlaubt eine Abbildung der Planelemente auf ein Stundenraster (z.B. 1. Stunde, 2. Stunde, Pause, etc.), das eine zeitlich abstrahierte Darstellung des Stundenplans ermöglicht.

Hier ein Beispiel für einen Zeitrahmen in einer Grundschule (Jahrgangsstufe 1):

"timeFrames": [
  {
    "id": "default",
    "shortName": "Unterricht",
    "longName": "Unterrichtsraster",
    "scopeOfWeek": [
      "mon",
      "tue",
      "wed",
      "thu",
      "fri"
    ],
    "timeSlots": [
      {
        "shortLabel": "1",
        "longLabel": "1. Stunde",
        "startTime": "08:00:00",
        "endTime": "08:45:00"
      },
      {
        "shortLabel": "2",
        "longLabel": "2. Stunde",
        "startTime": "09:05:00",
        "endTime": "09:50:00"
      },
      {
        "shortLabel": "3",
        "longLabel": "3. Stunde",
        "startTime": "10:10:00",
        "endTime": "10:55:00"
      },
      {
        "shortLabel": "4",
        "longLabel": "4. Stunde",
        "startTime": "11:00:00",
        "endTime": "11:45:00"
      },
      {
        "shortLabel": "5",
        "longLabel": "5. Stunde",
        "startTime": "12:20:00",
        "endTime": "13:05:00"
      }
    ]
  }
]

Standardisierte Codes¶

Standardisierte Codes erlauben die eindeutige Identifikation und Klassifikation von Daten. OpenT8 unterstützt OpenCodeList, ein generisches Standard-Datenformat zur Repräsentation von Code-Listen bzw. Schlüsselverzeichnissen.

Die folgenden Objekte besitzen jeweils ein Code-Attribut, das einen Verweis auf eine Code-Liste im OpenCodeList-Format darstellt.

absenceType-Objekt (Abwesenheitstyp)
activityType-Objekt (Aktivitätstyp)
courseType-Objekt (Kurstyp)
electronicAddressType-Objekt (elektronischer Addresstyp)
eventType-Objekt (Ereignistyp)
exemptionType-Objekt (Freistellungstyp)
gender-Objekt (Geschlecht)
groupType-Objekt (Gruppentyp)
personRole-Objekt (Personenrolle)
subject-Objekt (Fach)
supervisionType-Objekt (Aufsichtstyp)
teachingFormat-Objekt (Unterrichtsformat)

In einigen Fällen wird eine Standard-Code-Liste spezifiziert. Alle Standard-Code-Listen sind via CodeListHub verfügbar und abrufbar.

Hier ein Beispiel für einen Gruppentyp mit einem standardisierten Code:

"groupTypes": [
  {
    "id": "KL",
    "shortName": "KL",
    "longName": "Klasse",
    "code": {
      "codeListRef": {
        "canonicalUri": "urn:opene8:school:codelist:de:groupType",
        "locationUrls": [
          "https://api.codelisthub.org/v1/documents/urn%3Aopene8%3Aschool%3Acodelist%3Ade%3AgroupType"
        ]
      },
      "keyId": "key",
      "value": "KLA"
    }
  }
]

Externe Identifikatoren¶

Externe Identifikatoren erlauben das Verknüpfen von IDs aus Fremdsystemen mit Entitäten im OpenT8-Format. Unterstützt werden folgende Objekte:

building-Objekt (Gebäude)
campus-Objekt (Campus)
course-Objekt (Kurs)
group-Objekt (Gruppe)
person-Objekt (Person)
room-Objekt (Raum)
subject-Objekt (Fach)
supervisionArea-Objekt (Aufsichtsbereich)

Hier ein Beispiel für ein Fach mit zwei externen Identifikatoren:

"subjects": [
  {
    "id": "DE",
    "shortName": "DE",
    "longName": "Deutsch",
    "externalIds": [
      {
        "canonicalUri": "urn:myTimeTableApp1",
        "globallyUnique": true,
        "value": "eb002793-570e-45c7-af17-423831240b83"
      },
      {
        "canonicalUri": "urn:myTimeTableApp2",
        "globallyUnique": false,
        "value": "42"
      }
    ]
  }
]

Spezifikation¶

Versionierung¶

Die OpenT8-Spezifikation wird nach dem Schema major.minor.patch versioniert. Der Major-Minor-Teil der Versionsnummer (z.B. 0.8) MUSS den Funktionssatz der Spezifikation bezeichnen. Die Patch-Versionen betreffen Fehler in diesem Dokument oder stellen Klarstellungen zu diesem Dokument bereit, nicht zum Funktionsumfang. Werkzeuge, die OpenT8 in der Version 0.8 unterstützen, MÜSSEN mit allen 0.8.* Versionen von OpenT8 kompatibel sein. Die Patch-Version SOLLTE von den Werkzeugen NICHT berücksichtigt werden, so dass zum Beispiel kein Unterschied zwischen 0.8.1 und 0.8.2 gemacht wird.

Ein OpenT8-Dokument enthält stets ein obligatorisches Feld opent8, das die verwendete Version der OpenT8-Spezifikation angibt.

Format¶

Ein OpenT8-Dokument, das mit der OpenT8-Spezifikation konform ist, ist selbst ein JSON-Objekt, das im JSON-Format dargestellt werden kann.

Bei allen Feldnamen in der Spezifikation wird zwischen Groß- und Kleinschreibung unterschieden.

Das Schema sieht zwei Arten von Feldern vor: Fest definierte Felder, die einen deklarierten Namen haben, und freie Felder, deren Namen aber einem bestimmten Muster (Englisch: pattern) entsprechen MÜSSEN. Zusatzfelder MÜSSEN innerhalb des enthaltenen JSON-Objekts eindeutige Namen haben.

JSON Schema¶

JSON Schema ist eine Spezifikation zur Definition von JSON-Datenstrukturen. Ein JSON-Schema wird selbst deklarativ durch JSON ausgedrückt. Das OpenT8 Document Schema ist ein JSON-Schema für OpenT8-Dokumente.

Datums- und Zeitangaben¶

Die Formatierung von Datums- und Zeitangaben in OpenT8 orientiert sich an JSON Schema und RFC 3339, Abschnitt 5.6.

OpenT8 unterscheidet zwischen absoluten Zeitpunkten, lokalen Uhrzeiten und Kalenderdaten:

date-time: Datum und Uhrzeit mit Zeitzonenoffset, z. B. 2026-10-19T08:00:00Z oder 2026-10-19T08:00:00+02:00. Ein solcher Wert beschreibt einen eindeutigen absoluten Zeitpunkt.
localTime: Lokale Uhrzeit ohne Zeitzonenoffset, z. B. 08:00:00 oder 14:45:30.5. Dieses OpenT8-spezifische Format wird für die Zeitfenster eines Stundenrasters verwendet.
date: Kalenderdatum ohne Uhrzeit und Zeitzonenoffset, z. B. 2026-10-19.

Die Zeitzone eines Stundenplans wird durch die verpflichtende Eigenschaft schedule.timeZone festgelegt. Verwendet werden Zeitzonenbezeichner aus der IANA Time Zone Database.

Beispiel:

"timeZone": "Europe/Berlin"

Die angegebene Zeitzone ist maßgeblich für die Interpretation lokaler Uhrzeiten und Kalenderdaten sowie für die Berechnung wöchentlicher Wiederholungen. Dabei werden auch die jeweiligen Regeln für die Umstellung zwischen Sommer- und Winterzeit berücksichtigt.

Ein Zeitzonenoffset wie +02:00 ist dagegen keine vollständige Zeitzonenangabe, da er keine Informationen über zeitabhängige Zeitzonenregeln enthält.

Zeitspannen¶

Zeitspannen sind zeitliche Angaben, die durch einen Startzeitpunkt und einen Endzeitpunkt definiert werden.

OpenT8 unterscheidet zwischen einmaligen und wöchentlich wiederkehrenden Zeitspannen.

Einmalige Zeitspannen

Einmalige Zeitspannen (oneTimeExpression) werden durch zwei absolute Zeitpunkte definiert. Die Eigenschaften startTimepoint und endTimepoint verwenden das Format date-time.

Beispiel:

"temporalExpressions": [
  {
    "type": "onetime",
    "startTimepoint": "2026-10-19T08:00:00+02:00",
    "endTimepoint": "2026-10-19T08:45:00+02:00"
  }
]

Die angegebenen Zeitpunkte sind unabhängig von der Zeitzone des Stundenplans eindeutig. Anwendungen können sie bei Bedarf in die lokale Zeitzone umrechnen.

Wöchentlich wiederkehrende Zeitspannen

Wöchentlich wiederkehrende Zeitspannen (weeklyExpression) werden durch eine Referenzzeitspanne definiert, die einen absoluten Startzeitpunkt und einen absoluten Endzeitpunkt besitzt.

Aus dieser Referenzzeitspanne werden der lokale Wochentag, die lokalen Uhrzeiten sowie gegebenenfalls ein Tagesversatz zwischen Beginn und Ende abgeleitet. Maßgeblich hierfür ist die durch schedule.timeZone festgelegte Zeitzone.

Beispiel:

"temporalExpressions": [
  {
    "type": "weekly",
    "startTimepoint": "2026-08-31T08:00:00+02:00",
    "endTimepoint": "2026-08-31T08:45:00+02:00",
    "validFrom": "2026-10-01",
    "validTo": "2027-07-31"
  }
]

Die Referenzzeitspanne findet hier am Montag, dem 31. August 2026, von 08:00 bis 08:45 Uhr statt. Daraus ergibt sich eine wöchentliche Wiederholung jeden Montag zur gleichen lokalen Uhrzeit.

Die optionalen Eigenschaften validFrom und validTo legen den Gültigkeitszeitraum der Wiederholung fest. Sie können entweder ein Kalenderdatum (date) oder einen absoluten Zeitpunkt (date-time) enthalten.

Die Referenzveranstaltung selbst darf außerhalb dieses Gültigkeitszeitraums liegen. Im Beispiel beginnt die Gültigkeit am 1. Oktober 2026. Das erste gültige Vorkommen findet deshalb am Montag, dem 5. Oktober 2026, statt.

Fehlen validFrom oder validTo, gelten die entsprechenden Gültigkeitsgrenzen des übergeordneten schedule-Objekts.

Der tatsächlich gültige Zeitraum ergibt sich aus der Schnittmenge der Gültigkeitszeiträume des Stundenplans und des wöchentlichen Ausdrucks. Ob ein erzeugtes Vorkommen gültig ist, bestimmt sich anhand seines Startzeitpunkts.

Mit der optionalen Eigenschaft validWeeks kann die Wiederholung zusätzlich auf bestimmte Kalenderwochen eingeschränkt werden.

Die Wiederholungen werden anhand lokaler Kalendertage und Uhrzeiten berechnet. Dadurch bleiben beispielsweise Unterrichtsstunden auch nach einer Umstellung zwischen Sommer- und Winterzeit zur gleichen lokalen Uhrzeit bestehen. Die Berechnung erfolgt somit nicht durch das wiederholte Addieren einer festen Dauer von 168 Stunden.

Erstreckt sich die Referenzveranstaltung über mehrere lokale Kalendertage, wird der entsprechende Tagesversatz bei den Wiederholungen beibehalten.

Bei Zeitumstellungen gelten folgende Regeln:

Existiert eine für das Vorkommen benötigte lokale Uhrzeit aufgrund der Umstellung auf Sommerzeit nicht, wird das betreffende Vorkommen übersprungen.
Kommt eine für das Vorkommen benötigte lokale Uhrzeit aufgrund der Umstellung auf Winterzeit zweimal vor, wird der frühere der beiden möglichen Zeitpunkte verwendet.

Inklusive und exklusive Grenzen

Für Zeitspannen und Gültigkeitszeiträume gelten in OpenT8 folgende verbindliche Regeln:

Der Startzeitpunkt (startTimepoint, validFrom) ist inklusiv.
Der Endzeitpunkt (endTimepoint, validTo) ist exklusiv.

Eine Zeitspanne umfasst damit ihren Beginn, nicht jedoch ihr Ende. Diese Konvention ermöglicht insbesondere eine eindeutige und überschneidungsfreie Darstellung aufeinanderfolgender Zeitspannen.

Bei Gültigkeitsgrenzen im Format date beginnt die Gültigkeit um 00:00 Uhr des angegebenen Startdatums und endet um 00:00 Uhr des angegebenen Enddatums, jeweils in der Zeitzone des Stundenplans.

Soll ein Gültigkeitszeitraum einen vollständigen Kalendertag umfassen, wird validFrom auf diesen Kalendertag und validTo auf den darauffolgenden Kalendertag gesetzt.

Beispiel für den vollständigen 19. Oktober 2026:

"validFrom": "2026-10-19",
"validTo": "2026-10-20"

Auch mehrere vollständige Kalendertage lassen sich auf diese Weise darstellen.

Ein vollständiger Kalendertag kann alternativ mit einem einmaligen zeitlichen Ausdruck (oneTimeExpression) dargestellt werden. Dabei müssen die absoluten Zeitpunkte den jeweiligen lokalen Tagesgrenzen entsprechen.

Beispiel:

"temporalExpressions": [
  {
    "type": "onetime",
    "startTimepoint": "2026-10-25T00:00:00+02:00",
    "endTimepoint": "2026-10-26T00:00:00+01:00"
  }
]

Das Beispiel beschreibt den 25. Oktober 2026 in der Zeitzone Europe/Berlin. Da an diesem Tag die Umstellung von Sommer- auf Winterzeit stattfindet, umfasst die Zeitspanne tatsächlich 25 Stunden.

Ein vollständiger lokaler Kalendertag entspricht somit nicht notwendigerweise einer Dauer von 24 Stunden.

Kalenderwochen¶

Kalenderwochen werden durch ein JSON-Array mit formatierten Strings repräsentiert. Jeder formatierte String definiert die Menge der gewünschten ISO-Kalenderwochen für genau ein ISO-Wochenjahr.

Die Syntax lautet:

<Jahr>:(<Kalenderwoche>|<Kalenderwoche>-<Kalenderwoche>)[,(<Kalenderwoche>|<Kalenderwoche>-<Kalenderwoche>)]*

Eine Kalenderwoche ist nach ISO 8601 wie folgt definiert:

Kalenderwochen haben 7 Tage, beginnen an einem Montag und werden fortlaufend nummeriert.
Die Kalenderwoche 1 eines Jahres ist diejenige, die den ersten Donnerstag enthält.
Je nach Jahr kann es entweder 52 oder 53 Kalenderwochen geben.
Das ISO-Wochenjahr kann an den Jahresgrenzen vom Kalenderjahr abweichen. Beispielsweise gehört der 31. Dezember 2024 bereits zur Kalenderwoche 1 des ISO-Wochenjahres 2025.

Statt einzelner Kalenderwochen (z. B. 10) können auch Kalenderwochenbereiche (z. B. 10-12) definiert werden.

Ein Beispiel, bei dem für das ISO-Wochenjahr 2023 die Kalenderwochen 36, 38, 40, 42, 44, 46, 48 und 50 sowie für das ISO-Wochenjahr 2024 die ersten vier Wochen markiert sind:

"weeks": [
  "2023:36,38,40,42,44,46,48,50",
  "2024:1-4"
]

Bei wöchentlich wiederkehrenden Zeitspannen bezieht sich die Eigenschaft validWeeks auf die ISO-Kalenderwoche des lokalen Startdatums des jeweiligen Vorkommens in schedule.timeZone.

Farbwerte¶

Die Formatierung der Farbwerte in OpenT8 orientiert sich am hexadezimalen Farbsystem, so wie es auch im HTML-Standard definiert ist.

Eine hexadezimale Farbe wird angegeben mit: #RRGGBB, wobei die hexadezimalen Ganzzahlen RR (Rot), GG (Grün) und BB (Blau) die Komponenten der Farbe angeben.

Beispiele:

#ff0000 ist rot
#00ff00 ist grün
#0000ff ist blau
#ff8000 ist orange

URIs¶

Eine URI (Uniform Resource Identifier) ist eine Zeichenkette, die verwendet wird, um eine Ressource im Internet zu identifizieren. Es handelt sich hierbei um einen umfassenden Begriff, der sowohl URLs als auch URNs einschließt. Es gibt zwei Haupttypen von URIs:

URL (Uniform Resource Locator): Gibt den Standort einer Ressource an.
URN (Uniform Resource Name): Gibt den Namen einer Ressource an, ohne ihren Standort zu implizieren.

Eine URL (Uniform Resource Locator) ist ein URI-Typ, der beschreibt, wie eine Ressource im Netzwerk gefunden werden kann. Sie enthält Informationen wie das zu verwendende Protokoll (z.B. HTTPS), den Hostnamen (z.B. www.beispiel.de) und manchmal einen Pfad oder eine Abfragezeichenfolge, um die spezifische Ressource zu identifizieren.

Beispiel für eine URL:

https://www.beispiel.de/buecher/die-abenteuer-des-tom-sawyer.pdf

Hier:

https ist das Protokoll.
www.beispiel.de ist der Hostname.
/buecher/die-abenteuer-des-tom-sawyer.pdf ist der Pfad zur spezifischen Ressource.

Eine URN (Uniform Resource Name) ist ein URI-Typ, der eine eindeutige und dauerhafte Kennung für eine Ressource bereitstellt, ohne ihren Standort oder den Zugriffsweg zu beschreiben. URNs sollen als dauerhafte, standortunabhängige Ressourcenkennung dienen.

Beispiel für eine URN:

urn:isbn:978-3-96111-268-5

Hier:

urn zeigt an, dass es sich um eine URN handelt.
isbn ist der Namespace-Identifier.
978-3-96111-268-5 ist der spezifische Ressourcenname innerhalb des isbn Namespace.

Schema¶

OpenT8-Objekt¶

Dies ist das Wurzelobjekt eines OpenT8-Dokuments und enthält folgende Felder:

opent8: Definiert die Versionsnummer der OpenT8-Spezifikation. Dieses Feld ist ERFORDERLICH.
info: Metadaten zum Stundenplan. Dieses Objekt ist ERFORDERLICH.
absenceTypes: Eine Liste von Abwesenheitstypen. Es MUSS ein JSON-Array mit absenceType-Objekten sein.
activityTypes: Eine Liste von Aktivitätstypen. Es MUSS ein JSON-Array mit activityType-Objekten sein.
buildings: Eine Liste von Gebäuden. Es MUSS ein JSON-Array mit building-Objekten sein.
campuses: Eine Liste von Campussen. Es MUSS ein JSON-Array mit campus-Objekten sein.
courses: Eine Liste von Kursen. Es MUSS ein JSON-Array mit course-Objekten sein.
courseTypes: Eine Liste von Kurstypen. Es MUSS ein JSON-Array mit courseType-Objekten sein.
electronicAddressTypes: Eine Liste von elektronischen Adresstypen. Es MUSS ein JSON-Array mit electronicAddressType-Objekten sein.
eventTypes: Eine Liste von Ereignistypen. Es MUSS ein JSON-Array mit eventType-Objekten sein.
exemptionTypes: Eine Liste von Freistellungstypen. Es MUSS ein JSON-Array mit exemptionType-Objekten sein.
genders: Eine Liste von Angaben zum Personengeschlecht. Es MUSS ein JSON-Array mit gender-Objekten sein.
groups: Eine Liste von Gruppen. Es MUSS ein JSON-Array mit group-Objekten sein.
groupTypes: Eine Liste von Gruppentypen. Es MUSS ein JSON-Array mit groupType-Objekten sein.
persons: Eine Liste von Personen. Es MUSS ein JSON-Array mit person-Objekten sein.
personRoles: Eine Liste von Personenrollen. Es MUSS ein JSON-Array mit personRole-Objekten sein.
rooms: Eine Liste von Räumen. Es MUSS ein JSON-Array mit room-Objekten sein.
subjects: Eine Liste von Fächern. Es MUSS ein JSON-Array mit subject-Objekten sein.
supervisionAreas: Eine Liste von Aufsichtsbereichen. Es MUSS ein JSON-Array mit supervisionArea-Objekten sein.
supervisionTypes: Eine Liste von Aufsichtstypen. Es MUSS ein JSON-Array mit supervisionType-Objekten sein.
teachingFormats: Eine Liste von Unterrichtsformaten. Es MUSS ein JSON-Array mit teachingFormat-Objekten sein.
timeFrames: Eine Liste von Zeitrahmen. Es MUSS ein JSON-Array mit timeFrame-Objekten sein.
weeksPatterns: Eine Liste von Kalenderwochenmustern. Es MUSS ein JSON-Array mit weeksPattern-Objekten sein.
schedule: Die eigentliche zeitliche Verplanung. Dieses Objekt ist ERFORDERLICH.

absence-Objekt¶

Das absence-Objekt definiert eine Abwesenheit:

type

MUSS den Wert absence haben. Dieses Feld ist ERFORDERLICH und SOLLTE als erste Eigenschaft im JSON-Objekt definiert sein.

notes

Bemerkungen zur Abwesenheit.

absenceType.refId

Typ der Abwesenheit. Dies MUSS ein Verweis auf die id eines absenceType-Objekts sein. Ist absenceType angegeben, ist das Feld refId ERFORDERLICH.

appliesTo

Eine Person, eine Gruppe oder ein Raum, für welche(n) die Abwesenheit gilt. Dies MUSS ein JSON-Objekt mit folgenden Feldern sein:

refType : Die Typisierung des Feldes refId. Dieses Feld ist ERFORDERLICH.

Mögliche Werte sind:

Wert Beschreibung

person Eine Person ist abwesend.

group Eine Gruppe ist abwesend.

room Der Raum steht nicht zur Verfügung.
refId : Dies MUSS ein Verweis auf das Feld id eines vorhandenen person-Objekts, eines vorhandenen group-Objekts oder eines vorhandenen room-Objekts sein, jeweils in Abhängigkeit vom Wert in Feld refType. Dieses Feld ist ERFORDERLICH.

Dieses Objekt KANN erweitert werden.

absenceType-Objekt¶

Das absenceType-Objekt repräsentiert einen Abwesenheitstyp, mit dem Abwesenheiten kategorisiert werden können:

id

Eindeutige Identifikation des Abwesenheitstyps. Dieses Feld ist ERFORDERLICH.

code

Ein standardisierter Schlüssel. Dies MUSS ein externalCode-Objekt sein, das auf einen Code aus einer externen Code-Liste verweist.

Es wird keine Code-Liste empfohlen.

shortName

Kürzel des Abwesenheitstyp. Dieses Feld ist ERFORDERLICH.

longName

Ausführlicher Name des Abwesenheitstyp.

description

Eine kurze Beschreibung des Abwesenheitstyp.

Dieses Objekt KANN erweitert werden.

activity-Objekt¶

Das activity-Objekt definiert eine Aktivität:

type

MUSS den Wert activity haben. Dieses Feld ist ERFORDERLICH und SOLLTE als erste Eigenschaft im JSON-Objekt definiert sein.

id

Eindeutige Identifikation der Aktivität. Dieses Feld ist ERFORDERLICH.

shortName

Kürzel der Aktivität. Dieses Feld ist ERFORDERLICH.

longName

Ausführlicher Name der Aktivität.

description

Eine kurze Beschreibung der Aktivität.

color

Ein Farbwert (Hex-Kodierung) für die Aktivität.

classification

Klassifikation der Aktivität.

Folgende Werte sind definiert:

Wert	Beschreibung
`scheduled`	Wie geplant (das ist der Standardwert)
`additional`	Zusatzaktivität
`substitution`	Vertretungsaktivität

activityType.refId

Typ der Aktivität. Dies MUSS ein Verweis auf die id eines activityType-Objekts sein.

activityUrl

Eine URL zu einer externen Website mit zusätzlichen Infos zu dieser Aktivität.

groups

Eine Liste von teilnehmenden Gruppen. Dies MUSS ein JSON-Array mit Objekten sein, welche folgende Felder besitzen:

refId : Dies MUSS ein Verweis auf die id eines vorhandenen group-Objekts sein. Dieses Feld ist ERFORDERLICH.

attendees

Eine Liste von Teilnehmern und deren Rollen. Dies MUSS ein JSON-Array mit Objekten sein, welche folgende Felder besitzen:

refId : Dies MUSS ein Verweis auf die id eines vorhandenen person-Objekts sein. Dieses Feld ist ERFORDERLICH.
role.refId : Dies MUSS ein Verweis auf die id eines vorhandenen personRole-Objekts sein. Dieses Feld ist ERFORDERLICH.

rooms

Eine Liste von genutzten Räumen. Dies MUSS ein JSON-Array mit Objekten sein, welche folgende Felder besitzen:

refId : Dies MUSS ein Verweis auf die id eines vorhandenen room-Objekts sein. Dieses Feld ist ERFORDERLICH.

temporalExpressions

Eine Liste von zeitlichen Ausdrücken. Es MUSS ein JSON-Array mit oneTimeExpression-Objekten und/oder weeklyExpression-Objekten sein. Dieses Feld ist ERFORDERLICH.

Dieses Objekt KANN erweitert werden.

activityType-Objekt¶

Das activityType-Objekt repräsentiert einen Aktivitätstyp, mit dem Aktivitäten kategorisiert werden können:

id

Eindeutige Identifikation des Aktivitätstyps. Dieses Feld ist ERFORDERLICH.

code

Ein standardisierter Schlüssel. Dies MUSS ein externalCode-Objekt sein, das auf einen Code aus einer externen Code-Liste verweist.

Es wird keine Code-Liste empfohlen.

shortName

Kürzel des Aktivitätstyp. Dieses Feld ist ERFORDERLICH.

longName

Ausführlicher Name des Aktivitätstyp.

description

Eine kurze Beschreibung des Aktivitätstyp.

Dieses Objekt KANN erweitert werden.

announcement-Objekt¶

Das announcement-Objekt repräsentiert eine freie Mitteilung im Stundenplan:

type

MUSS den Wert announcement haben. Dieses Feld ist ERFORDERLICH und SOLLTE als erste Eigenschaft im JSON-Objekt definiert sein.

id

Eindeutige Identifikation der Mitteilung. Dieses Feld ist ERFORDERLICH.

shortDescription

Kurzbeschreibung der Mitteilung. Dieses Feld ist ERFORDERLICH.

longDescription

Ausführlicher Inhalt der Mitteilung.

notes

Bemerkungen zur Mitteilung.

color

Ein Farbwert (Hex-Kodierung) für die Mitteilung.

priority

Die Priorität der Mitteilung.

Folgende Werte sind definiert:

Wert	Beschreibung
`important`	Wichtig
`alarm`	Alarm

appliesTo

Eine Liste von Gruppen oder Personen, für welche die Mitteilung gilt. Dies MUSS ein JSON-Array mit Objekten sein, welche folgende Felder besitzen:

refType : Die Typisierung des Feldes refId. Dieses Feld ist ERFORDERLICH.

Mögliche Werte sind:

Wert Beschreibung

person Eine Person

group Eine Gruppe
refId : Dies MUSS ein Verweis auf das Feld id eines vorhandenen person-Objekts oder eines vorhandenen group-Objekts, jeweils in Abhängigkeit vom Wert in Feld refType. Dieses Feld ist ERFORDERLICH.

temporalExpressions

Eine Liste von zeitlichen Ausdrücken. Es MUSS ein JSON-Array mit oneTimeExpression-Objekten und/oder weeklyExpression-Objekten sein. Dieses Feld ist ERFORDERLICH.

Dieses Objekt KANN erweitert werden.

building-Objekt¶

Das building-Objekt repräsentiert ein Gebäude, in dem sich Räume befinden:

id: Eindeutige Identifikation des Gebäudes. Dieses Feld ist ERFORDERLICH.
shortName: Kürzel des Gebäudes. Dieses Feld ist ERFORDERLICH.
longName: Ausführlicher Name des Gebäudes.
description: Eine kurze Beschreibung des Gebäudes.
color: Ein Farbwert (Hex-Kodierung) für das Gebäude.
campus.refId: Der Campus, auf dem sich das Gebäude befindet. Dies MUSS ein Verweis auf die id eines campus-Objekts sein. Ist campus angegeben, ist das Feld refId ERFORDERLICH.
externalIds: Eine optionale Liste von externen Identifikatoren. Es MUSS ein JSON-Array mit externalId-Objekten sein.

Dieses Objekt KANN erweitert werden.

campus-Objekt¶

Das campus-Objekt repräsentiert einen Campus, auf dem sich Gebäude und/oder Aufsichtsbereiche befinden:

id: Eindeutige Identifikation des Campus. Dieses Feld ist ERFORDERLICH.
shortName: Kürzel des Campus. Dieses Feld ist ERFORDERLICH.
longName: Ausführlicher Name des Campus.
description: Eine kurze Beschreibung des Campus.
color: Ein Farbwert (Hex-Kodierung) für den Campus.
externalIds: Eine optionale Liste von externen Identifikatoren. Es MUSS ein JSON-Array mit externalId-Objekten sein.

Dieses Objekt KANN erweitert werden.

cancellation-Objekt¶

Das cancellation-Objekt definiert einen Ausfall einer Aktivität, einer Unterrichtseinheit oder einer Aufsicht:

type

MUSS den Wert cancellation haben. Dieses Feld ist ERFORDERLICH und SOLLTE als erste Eigenschaft im JSON-Objekt definiert sein.

message

Mitteilungstext zum Ausfall.

notes

Bemerkungen zum Ausfall.

behavior

Mögliches Verhalten

none : Keine Angabe oder nicht relevant
leaveLocation : Den Unterrichtsraum oder Bereich verlassen
stayInLocation : Im Unterrichtsraum oder Bereich bleiben

Dieses Objekt KANN erweitert werden.

course-Objekt¶

Das course-Objekt repräsentiert einen Kurs, in dem sich Gruppen und/oder Teilnehmer treffen und der Unterrichtseinheiten zugeordnet werden kann:

id

Eindeutige Identifikation des Kurses. Dieses Feld ist ERFORDERLICH.

shortName

Kürzel des Kurses. Dieses Feld ist ERFORDERLICH.

longName

Ausführlicher Name des Kurses.

description

Eine kurze Beschreibung des Kurses.

color

Ein Farbwert (Hex-Kodierung) für den Kurs.

subject.refId

Das zugeordnete Fach. Dies MUSS ein Verweis auf die id eines vorhandenen subject-Objekts sein. Ist subject angegeben, ist das Feld refId ERFORDERLICH.

courseNo

Eine Kursnummer.

courseType.refId

Ein Kurstyp zur Differenzierung des Kurses. Dies MUSS ein Verweis auf die id eines courseType-Objekts sein. Ist courseType angegeben, ist das Feld refId ERFORDERLICH.

courseUrl

Eine URL zu einer externen Website mit zusätzlichen Infos zu diesem Kurs.

groups

Eine Liste von teilnehmenden Gruppen. Dies MUSS ein JSON-Array mit Objekten sein, welche folgende Felder besitzen:

refId : Dies MUSS ein Verweis auf die id eines vorhandenen group-Objekts sein. Dieses Feld ist ERFORDERLICH.

attendees

Eine Liste von Teilnehmern und deren Rollen. Dies MUSS ein JSON-Array mit Objekten sein, welche folgende Felder besitzen:

refId : Dies MUSS ein Verweis auf die id eines vorhandenen person-Objekts sein. Dieses Feld ist ERFORDERLICH.
role.refId : Dies MUSS ein Verweis auf die id eines vorhandenen personRole-Objekts sein. Dieses Feld ist ERFORDERLICH.

validFrom

Definiert den inklusiven Beginn des Gültigkeitszeitraums des Kurses. Die Angabe kann entweder ein Kalenderdatum (date) oder ein absoluter Zeitpunkt (date-time gemäß RFC 3339) sein. Kalenderdaten werden als 00:00 Uhr in der Zeitzone des Stundenplans (schedule.timeZone) interpretiert.

validTo

Definiert das exklusive Ende des Gültigkeitszeitraums des Kurses. Die Angabe kann entweder ein Kalenderdatum (date) oder ein absoluter Zeitpunkt (date-time gemäß RFC 3339) sein. Kalenderdaten werden als 00:00 Uhr in der Zeitzone des Stundenplans (schedule.timeZone) interpretiert.

externalIds

Eine optionale Liste von externen Identifikatoren. Es MUSS ein JSON-Array mit externalId-Objekten sein.

Dieses Objekt KANN erweitert werden.

courseType-Objekt¶

Das courseType-Objekt repräsentiert die Art bzw. Differenzierung eines Kurses (z.B. Leistungskurs, Grundkurs etc.):

id

Eindeutige Identifikation des Kurstyps. Dieses Feld ist ERFORDERLICH.

code

Ein standardisierter Schlüssel. Dies MUSS ein externalCode-Objekt sein, das auf einen Code aus einer externen Code-Liste verweist.

Standardmäßig wird folgende Code-Liste EMPFOHLEN:

CanonicalURI	URL
`urn:opene8:school:codelist:de:courseType`	Link

shortName

Kürzel des Kurstyps. Dieses Feld ist ERFORDERLICH.

longName

Ausführlicher Name des Kurstyps.

description

Eine kurze Beschreibung des Kurstyps.

Dieses Objekt KANN erweitert werden.

electronicAddressType-Objekt¶

Das electronicAddressType-Objekt repräsentiert einen Adresstyp, mit dem elektronische Adressen (z.B. E-Mail, Telefon) kategorisiert werden können:

id

Eindeutige Identifikation des Addresstyps. Dieses Feld ist ERFORDERLICH.

code

Ein standardisierter Schlüssel. Dies MUSS ein externalCode-Objekt sein, das auf einen Code aus einer externen Code-Liste verweist.

Es wird keine Code-Liste empfohlen.

shortName

Kürzel des Addresstyps. Dieses Feld ist ERFORDERLICH.

longName

Ausführlicher Name des Addresstyps.

description

Eine kurze Beschreibung des Addresstyps.

Dieses Objekt KANN erweitert werden.

event-Objekt¶

Das event-Objekt repräsentiert einen Termin, der sich nicht durch eine Veranstaltung ausdrücken lässt (z.B. eine Prüfung oder ein Meeting):

type

MUSS den Wert event haben. Dieses Feld ist ERFORDERLICH und SOLLTE als erste Eigenschaft im JSON-Objekt definiert sein.

id

Eindeutige Identifikation des Termins. Dieses Feld ist ERFORDERLICH.

shortName

Kürzel des Termins. Dieses Feld ist ERFORDERLICH.

longName

Ausführlicher Name des Termins.

description

Eine kurze Beschreibung des Termins.

color

Ein Farbwert (Hex-Kodierung) für den Termin.

eventType.refId

Typ des Ereignisses. Dies MUSS ein Verweis auf die id eines eventType-Objekts sein. Ist eventType angegeben, ist das Feld refId ERFORDERLICH.

eventUrl

Eine URL zu einer externen Website mit zusätzlichen Infos zu diesem Ereignis.

groups

Eine Liste von teilnehmenden Gruppen. Dies MUSS ein JSON-Array mit Objekten sein, welche folgende Felder besitzen:

refId : Dies MUSS ein Verweis auf die id eines vorhandenen group-Objekts sein. Dieses Feld ist ERFORDERLICH.

attendees

Eine Liste von Teilnehmern und deren Rollen. Dies MUSS ein JSON-Array mit Objekten sein, welche folgende Felder besitzen:

refId : Dies MUSS ein Verweis auf die id eines vorhandenen person-Objekts sein. Dieses Feld ist ERFORDERLICH.
role.refId : Dies MUSS ein Verweis auf die id eines vorhandenen personRole-Objekts sein. Dieses Feld ist ERFORDERLICH.

rooms

Eine Liste von genutzten Räumen. Dies MUSS ein JSON-Array mit Objekten sein, welche folgende Felder besitzen:

refId : Dies MUSS ein Verweis auf die id eines vorhandenen room-Objekts sein. Dieses Feld ist ERFORDERLICH.

temporalExpressions

Eine Liste von zeitlichen Ausdrücken. Es MUSS ein JSON-Array mit oneTimeExpression-Objekten und/oder weeklyExpression-Objekten sein. Dieses Feld ist ERFORDERLICH.

Dieses Objekt KANN erweitert werden.

eventType-Objekt¶

Das eventType-Objekt repräsentiert einen Ereignistyp, mit dem Ereignisse kategorisiert werden können:

id

Eindeutige Identifikation des Ereignistyps. Dieses Feld ist ERFORDERLICH.

code

Ein standardisierter Schlüssel. Dies MUSS ein externalCode-Objekt sein, das auf einen Code aus einer externen Code-Liste verweist.

Es wird keine Code-Liste empfohlen.

shortName

Kürzel des Ereignistyps. Dieses Feld ist ERFORDERLICH.

longName

Ausführlicher Name des Ereignistyps.

description

Eine kurze Beschreibung des Ereignistyps.

Dieses Objekt KANN erweitert werden.

exemption-Objekt¶

Das exemption-Objekt definiert eine Freistellung:

type

MUSS den Wert exemption haben. Dieses Feld ist ERFORDERLICH und SOLLTE als erste Eigenschaft im JSON-Objekt definiert sein.

notes

Bemerkungen zur Freistellung.

exemptionType.refId

Typ des Freistellung. Dies MUSS ein Verweis auf die id eines exemptionType-Objekts sein. Ist exemptionType angegeben, ist das Feld refId ERFORDERLICH.

appliesTo

Eine Person, für welche(n) die Freistellung gilt. Dies MUSS ein JSON-Objekt mit folgenden Feldern sein:

refType : Die Typisierung des Feldes refId. Dieses Feld ist ERFORDERLICH.

Mögliche Werte sind:

Wert Beschreibung

person Eine Person ist freigestellt.
refId : Dies MUSS ein Verweis auf das Feld id eines vorhandenen person-Objekts sein, jeweils in Abhängigkeit vom Wert in Feld refType. Dieses Feld ist ERFORDERLICH.

Dieses Objekt KANN erweitert werden.

exemptionType-Objekt¶

Das exemptionType-Objekt repräsentiert einen Freistellungstyp, mit dem Freistellungen kategorisiert werden können:

id

Eindeutige Identifikation des Freistellungstyps. Dieses Feld ist ERFORDERLICH.

code

Ein standardisierter Schlüssel. Dies MUSS ein externalCode-Objekt sein, das auf einen Code aus einer externen Code-Liste verweist.

Es wird keine Code-Liste empfohlen.

shortName

Kürzel des Freistellungstyp. Dieses Feld ist ERFORDERLICH.

longName

Ausführlicher Name des Freistellungstyp.

description

Eine kurze Beschreibung des Freistellungstyp.

Dieses Objekt KANN erweitert werden.

externalCode-Objekt¶

Das externalCode-Objekt definiert einen Code aus einer externen Code-Liste im OpenCodeList-Format:

codeListRef: Ein Objekt, das auf eine externe Code-Liste verweist. Dieses Feld ist ERFORDERLICH.
codeListRef.canonicalUri: Ein JSON-String im Format uri. Diese URI identifiziert alle Versionen (zusammen) der referenzierten Code-Liste eindeutig. Dieses Feld ist ERFORDERLICH.
codeListRef.canonicalVersionUri: Ein JSON-String im Format uri. Diese URI identifiziert eine bestimmte Version der referenzierten Code-Liste.
codeListRef.locationUrls: Ein JSON-Array mit JSON-String-Werten im Format uri. Diese URIs sind vorgeschlagene Abruforte für die referenzierte Code-Liste, im OpenCodeList-Format.
keyId: Ein JSON-String mit einer ID, die auf ein key-Objekt in der unter codeListRef definierten externen Code-Liste verweist. Dieses Feld ist ERFORDERLICH.
value: Ein Code aus der externen Code-Liste. Dieses Feld ist ERFORDERLICH.

externalId-Objekt¶

Das externalId-Objekt definiert einen externen Identifikator:

canonicalUri: Ein JSON-String im Format uri. Diese URI legt den Namensraum des externen Identifikators fest bzw. gibt Auskunft darüber, zu wem der Identifikator gehört. Dieses Feld ist ERFORDERLICH.
globallyUnique: Ein JSON-Boolean, der angibt, ob der Identifikator eine globale Eindeutigkeit besitzt. Dieses Feld ist ERFORDERLICH.
value: Der eigentliche Identifikator-Wert. Dieses Feld ist ERFORDERLICH.

gap-Objekt¶

Das gap-Objekt repräsentiert eine Fehlstelle im Stundenplan:

type

MUSS den Wert gap haben. Dieses Feld ist ERFORDERLICH und SOLLTE als erste Eigenschaft im JSON-Objekt definiert sein.

id

Eindeutige Identifikation der Fehlstelle. Dieses Feld ist ERFORDERLICH.

notes

Bemerkungen zur Fehlstelle.

appliesTo

Eine Aktivität, eine Unterrichtseinheit oder eine Aufsicht, für welche(n) die Fehlstelle gilt. Dies MUSS ein JSON-Objekt mit folgenden Feldern sein:

refType : Die Typisierung des Feldes refId. Dieses Feld ist ERFORDERLICH.

Mögliche Werte sind:

Wert Beschreibung

activity Fehlstelle für eine Aktivität

lesson Fehlstelle für eine Unterrichtseinheit

supervision Fehlstelle für eine Aufsicht
refId : Dies MUSS ein Verweis auf das Feld id eines vorhandenen activity-Objekts, eines vorhandenen lesson-Objekts oder eines vorhandenen supervision-Objekts sein, jeweils in Abhängigkeit vom Wert in Feld refType. Dieses Feld ist ERFORDERLICH.

reasons

Eine Liste von Gründen. Es MUSS ein JSON-Array mit absence-Objekten und/oder exemption-Objekten sein.

resolutions

Eine Liste von Auflösungen. Es MUSS ein JSON-Array mit substitution-Objekten und/oder cancellation-Objekten sein.

temporalExpressions

Eine Liste von zeitlichen Ausdrücken. Es MUSS ein JSON-Array mit oneTimeExpression-Objekten und/oder weeklyExpression-Objekten sein. Dieses Feld ist ERFORDERLICH.

Dieses Objekt KANN erweitert werden.

gender-Objekt¶

Das gender-Objekt definiert das Geschlecht einer Person:

id

Eindeutige Identifikation des Geschlechts. Dieses Feld ist ERFORDERLICH.

code

Ein standardisierter Schlüssel. Dies MUSS ein externalCode-Objekt sein, das auf einen Code aus einer externen Code-Liste verweist.

Standardmäßig wird folgende Code-Liste EMPFOHLEN:

CanonicalURI	URL
`urn:opene8:core:codelist:de:gender`	Link

shortName

Kürzel des Geschlechts. Dieses Feld ist ERFORDERLICH.

longName

Ausführlicher Name des Geschlechts.

description

Eine kurze Beschreibung des Geschlechts.

Dieses Objekt KANN erweitert werden.

group-Objekt¶

Das group-Objekt repräsentiert eine Gruppe (z.B. Klasse, Jahrgang, etc.), der man Teilnehmer zuordnen kann:

id

Eindeutige Identifikation der Gruppe. Dieses Feld ist ERFORDERLICH.

shortName

Kürzel der Gruppe. Dieses Feld ist ERFORDERLICH.

longName

Ausführlicher Name der Gruppe.

description

Eine kurze Beschreibung der Gruppe.

color

Ein Farbwert (Hex-Kodierung) für die Gruppe.

groupType.refId

Typ der Gruppe. Dies MUSS ein Verweis auf die id eines groupType-Objekts sein. Ist groupType angegeben, ist das Feld refId ERFORDERLICH.

members

Eine Liste von Mitgliedern und deren Rollen. Dies MUSS ein JSON-Array mit Objekten sein, welche folgende Felder besitzen:

refId : Dies MUSS ein Verweis auf die id eines vorhandenen person-Objekts sein. Dieses Feld ist ERFORDERLICH.
role.refId : Dies MUSS ein Verweis auf die id eines vorhandenen personRole-Objekts sein. Dieses Feld ist ERFORDERLICH.

timeFrame.refId

Der Zeitrahmen der Gruppe. Dies MUSS ein Verweis auf die id eines timeFrame-Objekts sein. Diese Angabe macht nur Sinn, wenn sie vom Standardzeitrahmen des Stundenplans abweicht. Ist timeFrame angegeben, ist das Feld refId ERFORDERLICH.

validFrom

Definiert den inklusiven Beginn des Gültigkeitszeitraums der Gruppe. Die Angabe kann entweder ein Kalenderdatum (date) oder ein absoluter Zeitpunkt (date-time gemäß RFC 3339) sein. Kalenderdaten werden als 00:00 Uhr in der Zeitzone des Stundenplans (schedule.timeZone) interpretiert.

validTo

Definiert das exklusive Ende des Gültigkeitszeitraums der Gruppe. Die Angabe kann entweder ein Kalenderdatum (date) oder ein absoluter Zeitpunkt (date-time gemäß RFC 3339) sein. Kalenderdaten werden als 00:00 Uhr in der Zeitzone des Stundenplans (schedule.timeZone) interpretiert.

externalIds

Eine optionale Liste von externen Identifikatoren. Es MUSS ein JSON-Array mit externalId-Objekten sein.

Dieses Objekt KANN erweitert werden.

groupType-Objekt¶

Das groupType-Objekt repräsentiert einen Gruppentyp, mit dem Gruppen kategorisiert werden können:

id

Eindeutige Identifikation des Gruppentyps. Dieses Feld ist ERFORDERLICH.

code

Ein standardisierter Schlüssel. Dies MUSS ein externalCode-Objekt sein, das auf einen Code aus einer externen Code-Liste verweist.

Standardmäßig wird folgende Code-Liste EMPFOHLEN:

CanonicalURI	URL
`urn:opene8:school:codelist:de:groupType`	Link

shortName

Kürzel des Gruppentyps. Dieses Feld ist ERFORDERLICH.

longName

Ausführlicher Name des Gruppentyps.

description

Eine kurze Beschreibung des Gruppentyps.

Dieses Objekt KANN erweitert werden.

holiday-Objekt¶

Das holiday-Objekt repräsentiert eine schulfreie Zeit (Feiertage oder Schulferien):

type

MUSS den Wert holiday haben. Dieses Feld ist ERFORDERLICH und SOLLTE als erste Eigenschaft im JSON-Objekt definiert sein.

id

Eindeutige Identifikation der schulfreien Zeit. Dieses Feld ist ERFORDERLICH.

shortName

Kürzel der schulfreien Zeit. Dieses Feld ist ERFORDERLICH.

longName

Ausführlicher Name der schulfreien Zeit

description

Eine kurze Beschreibung der schulfreien Zeit.

color

Ein Farbwert (Hex-Kodierung) für die schulfreie Zeit.

holidayType

Die Typisierung des Termins. Dieses Feld ist ERFORDERLICH.

Mögliche Werte sind:

Wert	Beschreibung
`public`	Feiertag
`school`	Schulferien
`custom`	Benutzerdefinierte Freizeit

temporalExpressions

Eine Liste von zeitlichen Ausdrücken. Es MUSS ein JSON-Array mit oneTimeExpression-Objekten und/oder weeklyExpression-Objekten sein. Dieses Feld ist ERFORDERLICH.

Dieses Objekt KANN erweitert werden.

info-Objekt¶

Das info-Objekt enthält Metadaten zum Stundenplan:

title: Der Titel oder die Bezeichnung des Stundenplans. Dieses Feld ist ERFORDERLICH.
description: Eine kurze Beschreibung des Stundenplans
summary: Eine Zusammenfassung des Stundenplaninhalts.
publishedAt: Zeitpunkt der Veröffentlichung des Stundenplans.
publishedBy: Name der Person oder Organisation, die für die Veröffentlichung des Stundenplans verantwortlich ist.
language: Die Ausgabesprache des Stundenplans. Dies MUSS ein ISO 639-1 Sprachcode sein.
source: Quelle der Stundenplandaten.
source.name: Name des Dienstes, der Anwendung oder des Werkzeugs, mit dessen Hilfe die Stundenplandaten erzeugt wurden. Dieses Feld ist ERFORDERLICH.
source.version: Versionsnummer des Dienstes, der Anwendung oder des Werkzeugs, mit dessen Hilfe die Stundenplandaten erzeugt wurden.
source.url: Eine URL, unter der sich weitere Informationen finden lassen.

Dieses Objekt KANN erweitert werden.

Beispiel:

"info": {
  "title": "Stundenplan 2023/2024",
  "description": "Stundenplan für das Schuljahr 2023/2024",
  "summary": "Der aktuelle Stundenplan inklusive Aufsichten und Vertretungen.",
  "publishedAt": "2023-09-01T12:00:00Z",
  "publishedBy": "Meine-Schule, Berlin",
  "language": "de",
  "source": {
    "name": "MyTimeTableApp",
    "version": "1.0"
  }
}

lesson-Objekt¶

Das lesson-Objekt repräsentiert eine Veranstaltung bzw. Unterrichtseinheit, die einem Kurs zugeordnet ist und zeitlich verplant wird:

type

MUSS den Wert lesson haben. Dieses Feld ist ERFORDERLICH und SOLLTE als erste Eigenschaft im JSON-Objekt definiert sein.

id

Eindeutige Identifikation der Veranstaltung. Dieses Feld ist ERFORDERLICH.

course.refId

Der zugeordnete Kurs. Dies MUSS ein Verweis auf die id eines course-Objekts sein. Dieses Feld ist ERFORDERLICH.

classification

Klassifikation der Veranstaltung.

Folgende Werte sind definiert:

Wert	Beschreibung
`scheduled`	Wie geplant (das ist der Standardwert)
`additional`	Zusatzunterricht
`substitution`	Vertretungsunterricht

notes

Bemerkungen zur Veranstaltung.

color

Ein Farbwert (Hex-Kodierung) für die Veranstaltung.

teachingFormat.refId

Unterrichtsformat. Dies MUSS ein Verweis auf die id eines teachingFormat-Objekts sein.

groups

Eine Liste von teilnehmenden Gruppen. Dies MUSS ein JSON-Array mit Objekten sein, welche folgende Felder besitzen:

refId : Dies MUSS ein Verweis auf die id eines vorhandenen group-Objekts sein. Dieses Feld ist ERFORDERLICH.

attendees

Eine Liste von Teilnehmern und deren Rollen. Dies MUSS ein JSON-Array mit Objekten sein, welche folgende Felder besitzen:

refId : Dies MUSS ein Verweis auf die id eines vorhandenen person-Objekts sein. Dieses Feld ist ERFORDERLICH.
role.refId : Dies MUSS ein Verweis auf die id eines vorhandenen personRole-Objekts sein. Dieses Feld ist ERFORDERLICH.

rooms

Eine Liste von genutzten Räumen. Dies MUSS ein JSON-Array mit Objekten sein, welche folgende Felder besitzen:

refId : Dies MUSS ein Verweis auf die id eines vorhandenen room-Objekts sein. Dieses Feld ist ERFORDERLICH.

temporalExpressions

Eine Liste von zeitlichen Ausdrücken. Es MUSS ein JSON-Array mit oneTimeExpression-Objekten und/oder weeklyExpression-Objekten sein. Dieses Feld ist ERFORDERLICH.

Dieses Objekt KANN erweitert werden.

oneTimeExpression-Objekt¶

Das oneTimeExpression-Objekt definiert einen einmaligen zeitlichen Ausdruck:

type

MUSS den Wert onetime haben. Dieses Feld ist ERFORDERLICH und SOLLTE als erste Eigenschaft im JSON-Objekt definiert sein.

startTimepoint

Startzeitpunkt (RFC 3339) des zeitlichen Ausdrucks. Dieses Feld ist ERFORDERLICH.

endTimepoint

Endzeitpunkt (RFC 3339) des zeitlichen Ausdrucks. Dieses Feld ist ERFORDERLICH.

operation

Soll der zeitliche Ausdruck hinzugefügt oder abgezogen werden?

include : Findet statt (das ist der Standardwert)
exclude : Findet nicht statt

Das folgende Beispiel zeigt ein oneTimeExpression-Objekt, das sich über mehrere Tage erstreckt:

"temporalExpressions": [
  {
    "type": "onetime",
    "startTimepoint": "2023-12-23T12:00:00Z",
    "endTimepoint": "2024-01-05T12:00:00Z"
  }
]

person-Objekt¶

Das person-Objekt repräsentiert Mitglieder einer Gruppe bzw. Teilnehmer eines Kurses, einer Veranstaltung, einer Aufsicht eines Ereignisses oder einer Aktivität:

id

Eindeutige Identifikation der Person. Dieses Feld ist ERFORDERLICH.

name.shortName

Kürzel der Person. Dieses Feld ist ERFORDERLICH.

name.fullName

Der komplett ausgeschriebene Name der Person.

name.sortingName

Der Name der Person, optimiert für eine gewünschte alphanumerische Sortierung in einer Liste.

name.salutations

Die Liste der Anreden (z.B. "Herr", "Frau", etc.) der Person. Dies MUSS ein JSON-String-Array sein.

name.title

Der Titel (z.B. "Dr.", "Prof. Dr.", etc.) der Person.

name.familyName

Familienname oder Nachname der Person.

name.declaredName

Deklarierte Name der Person (z.B. Ehename oder Lebenspartnerschaftsname).

name.declaredNameType

Die Typisierung des Feldes name.declaredName.

Mögliche Werte sind:

Wert	Beschreibung
`marriedName`	Ehename
`civilPartnershipName`	Lebenspartnerschaftsname

Der Standardwert ist `marriedName`.

name.middleNames

Mittelnamen der Person. Dies MUSS ein JSON-String-Array sein.

name.givenName

Vorname der Person.

name.nameSuffixes

Namenszusätze (z.B. "Jr.", "MdB") der Person. Dies MUSS ein JSON-String-Array sein.

name.nickName

Rufname der Person.

gender.refId

Geschlecht der Person. Dies MUSS ein Verweis auf die id eines gender-Objekts sein.

birthdate

Geburtsdatum (date) der Person.

electronicAddresses

Liste der digitalen Adressen (z.B. E-Mail, Telefon, etc.)

electronicAddresses.*.addressType.refId

Art der elektronischen Adresse. Dies MUSS ein Verweis auf die id eines electronicAddressType-Objekts sein.

electronicAddresses.*.identifier

Kennung dieser elektronischen Adresse (z.B. die konkrete E-Mail-Adresse)

color

Ein Farbwert (Hex-Kodierung) für die Person.

timeFrame.refId

Der zugeordnete Zeitrahmen der Person. Dies MUSS ein Verweis auf die id eines timeFrame-Objekts sein. Diese Angabe macht nur Sinn, wenn sie vom Standardzeitrahmen des Stundenplans abweicht.

externalIds

Eine optionale Liste von externen Identifikatoren. Es MUSS ein JSON-Array mit externalId-Objekten sein.

Dieses Objekt KANN erweitert werden.

Hinweis

Die Untereigenschaften von name sind so spezifiziert, dass sie kompatibel (also 1:1 abgebildet werden können) mit der XÖV-Kernkomponente NameNatuerlichePerson sind.

personRole-Objekt¶

Das personRole-Objekt repräsentiert eine Rolle, mit der Mitglieder oder Teilnehmer kategorisiert werden können:

id

Eindeutige Identifikation der Rolle. Dieses Feld ist ERFORDERLICH.

code

Ein standardisierter Schlüssel. Dies MUSS ein externalCode-Objekt sein, das auf einen Code aus einer externen Code-Liste verweist.

Standardmäßig wird folgende Code-Liste EMPFOHLEN:

CanonicalURI	URL
`urn:opene8:school:codelist:de:personRole`	Link

shortName

Kürzel der Rolle. Dieses Feld ist ERFORDERLICH.

longName

Ausführlicher Name der Rolle.

description

Eine kurze Beschreibung der Rolle.

Dieses Objekt KANN erweitert werden.

room-Objekt¶

Das room-Objekt repräsentiert einen Raum, in dem Unterricht oder ein anderweitiges Ereignis stattfindet:

id: Eindeutige Identifikation des Raums. Dieses Feld ist ERFORDERLICH.
shortName: Kürzel des Raums. Dieses Feld ist ERFORDERLICH.
longName: Ausführlicher Name des Raums.
description: Eine kurze Beschreibung des Raums.
color: Ein Farbwert (Hex-Kodierung) für den Raum.
building.refId: Das Gebäude, in dem sich der Raum befindet. Dies MUSS ein Verweis auf die id eines building-Objekts sein.
externalIds: Eine optionale Liste von externen Identifikatoren. Es MUSS ein JSON-Array mit externalId-Objekten sein.

Dieses Objekt KANN erweitert werden.

schedule-Objekt¶

Das schedule-Objekt enthält die eigentliche zeitliche Verplanung:

timeZone: Definiert die Zeitzone des Stundenplans anhand eines Bezeichners aus der IANA Time Zone Database (z. B. Europe/Berlin). Die Zeitzone ist maßgeblich für die Interpretation lokaler Uhrzeiten und Kalenderdaten und berücksichtigt auch die Umstellung zwischen Sommer- und Winterzeit. Dieses Feld ist ERFORDERLICH.
validFrom: Definiert den inklusiven Beginn des Gültigkeitszeitraums des Stundenplans. Die Angabe kann entweder ein Kalenderdatum (date) oder ein absoluter Zeitpunkt (date-time gemäß RFC 3339) sein. Kalenderdaten werden als 00:00 Uhr in der Zeitzone des Stundenplans (schedule.timeZone) interpretiert. Dieses Feld ist ERFORDERLICH.
validTo: Definiert das exklusive Ende des Gültigkeitszeitraums des Stundenplans. Die Angabe kann entweder ein Kalenderdatum (date) oder ein absoluter Zeitpunkt (date-time gemäß RFC 3339) sein. Kalenderdaten werden als 00:00 Uhr in der Zeitzone des Stundenplans (schedule.timeZone) interpretiert. Dieses Feld ist ERFORDERLICH.
defaultTimeFrame.refId: Verweis auf den Standardzeitrahmen. Dies MUSS ein Verweis auf die id eines timeFrame-Objekts sein.
scheduleElements: Eine Liste von Planelementen. Es MUSS ein JSON-Array mit activity-Objekten, announcement-Objekten, event-Objekten, gap-Objekten, holiday-Objekten, lesson-Objekten und/oder supervision-Objekten sein.

Dieses Objekt KANN erweitert werden.

subject-Objekt¶

Das subject-Objekt repräsentiert ein Fach, das mit Kursen verknüpft werden kann:

id

Eindeutige Identifikation des Fachs. Dieses Feld ist ERFORDERLICH.

code

Ein standardisierter Schlüssel. Dies MUSS ein externalCode-Objekt sein, das auf einen Code aus einer externen Code-Liste verweist.

Standardmäßig wird folgende Code-Liste EMPFOHLEN:

CanonicalURI	URL
`urn:opene8:school:codelist:de:subject`	Link

shortName

Kürzel des Fachs. Dieses Feld ist ERFORDERLICH.

longName

Ausführlicher Name des Fachs.

description

Eine kurze Beschreibung des Fachs.

color

Ein Farbwert (Hex-Kodierung) für das Fach.

externalIds

Eine optionale Liste von externen Identifikatoren. Es MUSS ein JSON-Array mit externalId-Objekten sein.

Dieses Objekt KANN erweitert werden.

substitution-Objekt¶

Das substitution-Objekt definiert eine Vertretung:

type

MUSS den Wert substitution haben. Dieses Feld ist ERFORDERLICH und SOLLTE als erste Eigenschaft im JSON-Objekt definiert sein.

message

Mitteilungstext zur Vertretung.

notes

Bemerkungen zur Vertretung.

realizedBy

Eine Aktivität, eine Unterrichtseinheit oder eine Aufsicht, welche die Vertretung darstellt. Dies MUSS ein JSON-Objekt mit folgenden Feldern sein:

refType : Die Typisierung des Feldes refId. Dieses Feld ist ERFORDERLICH.

Mögliche Werte sind:

Wert Beschreibung

activity Vertretung durch eine Aktivität

lesson Vertretung durch eine Unterrichtseinheit

supervision Vertretung durch eine Aufsicht
refId : Dies MUSS ein Verweis auf das Feld id eines vorhandenen activity-Objekts, eines vorhandenen lesson-Objekts oder eines vorhandenen supervision-Objekts sein, jeweils in Abhängigkeit vom Wert in Feld refType. Dieses Feld ist ERFORDERLICH.

Dieses Objekt KANN erweitert werden.

supervision-Objekt¶

Das supervision-Objekt repräsentiert eine Aufsicht, die einem oder mehreren Aufsichtsbereichen zugeordnet ist und zeitlich verplant wird:

type

MUSS den Wert supervision haben. Dieses Feld ist ERFORDERLICH und SOLLTE als erste Eigenschaft im JSON-Objekt definiert sein.

id

Eindeutige Identifikation der Aufsicht. Dieses Feld ist ERFORDERLICH.

notes

Bemerkungen zur Aufsicht.

color

Ein Farbwert (Hex-Kodierung) für die Aufsicht.

classification

Klassifikation der Aufsicht.

Folgende Werte sind definiert:

Wert	Beschreibung
`scheduled`	Wie geplant (das ist der Standardwert)
`additional`	Zusatzaufsicht
`substitution`	Vertretungsaufsicht

supervisionType.refId

Typ der Aufsicht. Dies MUSS ein Verweis auf die id eines supervisionType-Objekts sein.

attendees

Eine Liste von Teilnehmern und deren Rollen. Dies MUSS ein JSON-Array mit Objekten sein, welche folgende Felder besitzen:

refId : Dies MUSS ein Verweis auf die id eines vorhandenen person-Objekts sein. Dieses Feld ist ERFORDERLICH.
role.refId : Dies MUSS ein Verweis auf die id eines vorhandenen personRole-Objekts sein. Dieses Feld ist ERFORDERLICH.

areas

Eine Liste von betroffenen Aufsichtsbereichen. Dies MUSS ein JSON-Array mit Objekten sein, welche folgende Felder besitzen:

refId : Dies MUSS ein Verweis auf die id eines vorhandenen supervisionArea-Objekts sein. Dieses Feld ist ERFORDERLICH.

temporalExpressions

Eine Liste von zeitlichen Ausdrücken. Es MUSS ein JSON-Array mit oneTimeExpression-Objekten und/oder weeklyExpression-Objekten sein. Dieses Feld ist ERFORDERLICH.

Dieses Objekt KANN erweitert werden.

supervisionArea-Objekt¶

Das supervisionArea-Objekt repräsentiert einen Aufsichtsbereich, für den Aufsichten verplant werden können:

id: Eindeutige Identifikation des Aufsichtsbereichs. Dieses Feld ist ERFORDERLICH.
shortName: Kürzel des Aufsichtsbereichs. Dieses Feld ist ERFORDERLICH.
longName: Ausführlicher Name des Aufsichtsbereichs.
description: Eine kurze Beschreibung des Aufsichtsbereichs.
color: Ein Farbwert (Hex-Kodierung) für den Aufsichtsbereich.
campus.refId: Der Campus, auf dem sich der Aufsichtsbereich befindet. Dies MUSS ein Verweis auf die id eines campus-Objekts sein.
timeFrame.refId: Der Zeitrahmen des Aufsichtsbereichs. Dies MUSS ein Verweis auf die id eines timeFrame-Objekts sein.
externalIds: Eine optionale Liste von externen Identifikatoren. Es MUSS ein JSON-Array mit externalId-Objekten sein.

Dieses Objekt KANN erweitert werden.

supervisionType-Objekt¶

Das supervisionType-Objekt repräsentiert einen Aufsichtstyp, mit dem Aufsichten kategorisiert werden können:

id

Eindeutige Identifikation des Aufsichtstyps. Dieses Feld ist ERFORDERLICH.

code

Ein standardisierter Schlüssel. Dies MUSS ein externalCode-Objekt sein, das auf einen Code aus einer externen Code-Liste verweist.

Standardmäßig wird keine Code-Liste empfohlen.

shortName

Kürzel des Aufsichtstyps. Dieses Feld ist ERFORDERLICH.

longName

Ausführlicher Name des Aufsichtstyps.

description

Eine kurze Beschreibung des Aufsichtstyps.

Dieses Objekt KANN erweitert werden.

teachingFormat-Objekt¶

Das teachingFormat-Objekt repräsentiert ein Unterrichtsformat, mit dem Unterrichtseinheiten kategorisiert werden können:

id

Eindeutige Identifikation des Unterrichtsformats. Dieses Feld ist ERFORDERLICH.

code

Ein standardisierter Schlüssel. Dies MUSS ein externalCode-Objekt sein, das auf einen Code aus einer externen Code-Liste verweist.

Standardmäßig wird folgende Code-Liste EMPFOHLEN:

CanonicalURI	URL
`urn:opene8:school:codelist:de:teachingFormat`	Link

shortName

Kürzel des Unterrichtsformats. Dieses Feld ist ERFORDERLICH.

longName

Ausführlicher Name des Unterrichtsformats.

description

Eine kurze Beschreibung des Unterrichtsformats.

Dieses Objekt KANN erweitert werden.

timeFrame-Objekt¶

Das timeFrame-Objekt definiert einen Zeitrahmen, mit dessen Hilfe sich die Uhrzeiten der Planelemente auf ein abstrahiertes Raster (z.B. 1. Stunde, 2. Stunde, Pause, etc.) abbilden:

id

Eindeutige Identifikation des Zeitrahmens. Dieses Feld ist ERFORDERLICH.

shortName

Kürzel des Zeitrahmens. Dieses Feld ist ERFORDERLICH.

longName

Ausführlicher Name des Zeitrahmens.

description

Eine kurze Beschreibung des Zeitrahmens.

scopeOfWeek

Die Menge der Wochentage, die bei einer wöchentlichen Darstellung des Stundenplans berücksichtigt werden sollen (z.B. nur Montag bis Samstag). Dies MUSS ein JSON-String-Array sein. Dieses Feld ist ERFORDERLICH.

Folgende Werte sind definiert:

Wert	Beschreibung
`mon`	Montag
`tue`	Dienstag
`wed`	Mittwoch
`thu`	Donnerstag
`fri`	Freitag
`sat`	Samstag
`sun`	Sonntag

startOfWeek

Der Wochentag, mit dem bei einer wöchentlichen Darstellung des Stundenplans begonnen werden soll. Der Standardwert ist mon.

Folgende Werte sind definiert:

Wert	Beschreibung
`mon`	Montag
`tue`	Dienstag
`wed`	Mittwoch
`thu`	Donnerstag
`fri`	Freitag
`sat`	Samstag
`sun`	Sonntag

timeSlots

Eine Liste von benannten Zeitfenstern, welche die Abstraktion des Zeitrahmens definieren. Dies MUSS ein JSON-Array mit timeSlot-Objekten sein. Dieses Feld ist ERFORDERLICH.

Dieses Objekt KANN erweitert werden.

timeSlot-Objekt¶

Das timeSlot-Objekt definiert ein benanntes Zeitfenster für einen Zeitrahmen (z. B. 1. Stunde von 08:00 bis 08:45 Uhr). Die Uhrzeiten werden als lokale Uhrzeiten in der Zeitzone des Stundenplans (schedule.timeZone) interpretiert.

shortLabel: Kürzel des Zeitfensters. Dieses Feld ist ERFORDERLICH.
longLabel: Ausführlicher Name des Zeitfensters.
color: Ein Farbwert (Hex-Kodierung) für das Zeitfenster.
startTime: Definiert die inklusive lokale Startuhrzeit des Zeitfensters (localTime), ohne Zeitzonenoffset. Dieses Feld ist ERFORDERLICH.
endTime: Definiert die exklusive lokale Enduhrzeit des Zeitfensters (localTime), ohne Zeitzonenoffset. Dieses Feld ist ERFORDERLICH.

Dieses Objekt KANN erweitert werden.

weeklyExpression-Objekt¶

Das weeklyExpression-Objekt definiert einen sich wöchentlich wiederholenden zeitlichen Ausdruck. Die Wiederholung basiert auf einer Referenzveranstaltung, aus der der lokale Wochentag, die lokalen Uhrzeiten und gegebenenfalls ein Tagesversatz abgeleitet werden.

type

MUSS den Wert weekly haben. Dieses Feld ist ERFORDERLICH und SOLLTE als erste Eigenschaft im JSON-Objekt definiert sein.

startTimepoint

Definiert den inklusiven Startzeitpunkt der Referenzveranstaltung (date-time gemäß RFC 3339). Aus diesem absoluten Zeitpunkt werden der Wochentag und die lokale Startuhrzeit in der Zeitzone des Stundenplans (schedule.timeZone) abgeleitet. Dieses Feld ist ERFORDERLICH.

endTimepoint

Definiert den exklusiven Endzeitpunkt der Referenzveranstaltung (date-time gemäß RFC 3339). Aus diesem absoluten Zeitpunkt werden die lokale Enduhrzeit und gegebenenfalls der Tagesversatz zum Startzeitpunkt in der Zeitzone des Stundenplans (schedule.timeZone) abgeleitet. Dieses Feld ist ERFORDERLICH.

validFrom

Definiert den inklusiven Beginn des Gültigkeitszeitraums der wöchentlichen Wiederholung. Die Angabe kann entweder ein Kalenderdatum (date) oder ein absoluter Zeitpunkt (date-time gemäß RFC 3339) sein. Kalenderdaten werden als 00:00 Uhr in der Zeitzone des Stundenplans (schedule.timeZone) interpretiert. Ist dieses Feld nicht definiert, gilt der Gültigkeitsbeginn des übergeordneten schedule-Objekts.

validTo

Definiert das exklusive Ende des Gültigkeitszeitraums der wöchentlichen Wiederholung. Die Angabe kann entweder ein Kalenderdatum (date) oder ein absoluter Zeitpunkt (date-time gemäß RFC 3339) sein. Kalenderdaten werden als 00:00 Uhr in der Zeitzone des Stundenplans (schedule.timeZone) interpretiert. Ist dieses Feld nicht definiert, gilt das Gültigkeitsende des übergeordneten schedule-Objekts.

validWeeks

Eine Liste von ISO-Kalenderwochen, in denen sich der zeitliche Ausdruck wiederholt. Maßgeblich ist die ISO-Kalenderwoche des lokalen Startdatums des jeweiligen Vorkommens in schedule.timeZone. Ist dieses Feld nicht definiert, findet die Wiederholung in jeder Woche innerhalb des Gültigkeitszeitraums statt.

Dieses Feld MUSS entweder ein JSON-String-Array mit eingebetteten Kalenderwochen oder ein JSON-Objekt mit einem Verweis (validWeeks.refId) auf die id eines weeksPattern-Objekts sein.

operation

Legt fest, ob der zeitliche Ausdruck hinzugefügt oder ausgeschlossen werden soll.

include: Findet statt (das ist der Standardwert).
exclude: Findet nicht statt.

Berechnung der Wiederholungen

Die Eigenschaften startTimepoint und endTimepoint definieren ausschließlich die Referenzveranstaltung. Diese darf auch außerhalb des Gültigkeitszeitraums liegen.

Wöchentliche Wiederholungen werden anhand des lokalen Wochentags und der lokalen Uhrzeiten der Referenzveranstaltung berechnet. Dadurch finden wiederkehrende Veranstaltungen unabhängig von Sommer- und Winterzeit immer zur gleichen lokalen Uhrzeit statt.

Der tatsächlich gültige Zeitraum ergibt sich aus der Schnittmenge der Gültigkeitszeiträume des schedule-Objekts und des weeklyExpression-Objekts. Ob ein erzeugtes Vorkommen gültig ist, bestimmt sich anhand seines Startzeitpunkts.

Bei Zeitumstellungen gelten folgende Regeln:

Existiert eine für das Vorkommen benötigte lokale Uhrzeit aufgrund der Umstellung auf Sommerzeit nicht, wird das betreffende Vorkommen übersprungen.
Kommt eine für das Vorkommen benötigte lokale Uhrzeit aufgrund der Umstellung auf Winterzeit zweimal vor, wird der frühere der beiden möglichen Zeitpunkte verwendet.

Beispiele

Das folgende Beispiel zeigt ein weeklyExpression-Objekt, bei dem für das ISO-Wochenjahr 2023 die Kalenderwochen 36, 38, 40, 42, 44, 46, 48 und 50 sowie für das ISO-Wochenjahr 2024 die ersten vier Wochen ausgewählt sind:

"temporalExpressions": [
  {
    "type": "weekly",
    "startTimepoint": "2023-09-08T10:30:00+02:00",
    "endTimepoint": "2023-09-08T11:15:00+02:00",
    "validWeeks": [
      "2023:36,38,40,42,44,46,48,50",
      "2024:1-4"
    ]
  }
]

Bei schedule.timeZone = "Europe/Berlin" beschreibt die Referenzveranstaltung einen Freitag von 10:30 bis 11:15 Uhr. Die Wiederholungen finden in den ausgewählten Kalenderwochen jeweils freitags zur gleichen lokalen Uhrzeit statt, sofern sie innerhalb des Gültigkeitszeitraums des Stundenplans liegen.

Das gleiche Beispiel mit einem Verweis auf ein weeksPattern-Objekt:

"temporalExpressions": [
  {
    "type": "weekly",
    "startTimepoint": "2023-09-08T10:30:00+02:00",
    "endTimepoint": "2023-09-08T11:15:00+02:00",
    "validWeeks": {
      "refId": "weeksPattern-1"
    }
  }
]

Im folgenden Beispiel liegt die Referenzveranstaltung außerhalb des Gültigkeitszeitraums:

"temporalExpressions": [
  {
    "type": "weekly",
    "startTimepoint": "2026-08-31T08:00:00+02:00",
    "endTimepoint": "2026-08-31T08:45:00+02:00",
    "validFrom": "2026-10-01",
    "validTo": "2027-07-31"
  }
]

Bei schedule.timeZone = "Europe/Berlin" legt die Referenzveranstaltung eine wöchentliche Wiederholung am Montag von 08:00 bis 08:45 Uhr fest. Da der Gültigkeitszeitraum erst am 1. Oktober 2026 beginnt, findet das erste gültige Vorkommen am Montag, dem 5. Oktober 2026, statt, sofern der Gültigkeitszeitraum des Stundenplans dieses Datum einschließt.

weeksPattern-Objekt¶

Das weeksPattern-Objekt definiert ein benanntes Kalenderwochenmuster, auf das weeklyExpression-Objekte über die Eigenschaft validWeeks verweisen können. Ein Wochenmuster legt fest, in welchen ISO-Kalenderwochen eines oder mehrerer ISO-Wochenjahre wöchentliche Wiederholungen stattfinden.

id

Eindeutige Identifikation des Wochenmusters. Dieses Feld ist ERFORDERLICH.

shortName

Kürzel des Wochenmusters. Dieses Feld ist ERFORDERLICH.

longName

Ausführlicher Name des Wochenmusters.

description

Eine kurze Beschreibung des Wochenmusters.

weeks

Definiert die ISO-Kalenderwochen, für die das Wochenmuster gilt. Die Angabe MUSS ein JSON-String-Array sein. Jeder Eintrag enthält ein ISO-Wochenjahr sowie eine Liste einzelner Kalenderwochen oder Kalenderwochenbereiche. Dieses Feld ist ERFORDERLICH.

Ein weeklyExpression-Objekt, das auf dieses Wochenmuster verweist, wird nur in den angegebenen Kalenderwochen wiederholt, sofern das jeweilige Vorkommen innerhalb seines Gültigkeitszeitraums liegt. Maßgeblich ist die ISO-Kalenderwoche des lokalen Startdatums des jeweiligen Vorkommens in der Zeitzone des Stundenplans (schedule.timeZone).

Kalenderwochen, die nicht ausdrücklich angegeben sind, werden nicht berücksichtigt. Das Wochenmuster wird nicht automatisch auf weitere ISO-Wochenjahre übertragen.

Beispiel

Das folgende Beispiel zeigt zwei weeksPattern-Objekte. Das erste definiert ausgewählte ungerade Kalenderwochen, das zweite ausgewählte gerade Kalenderwochen des ISO-Wochenjahres 2024:

"weeksPatterns": [
  {
    "id": "pattern-A",
    "shortName": "Pattern A",
    "weeks": [
      "2024:35,37,39,41,43,45,47,49"
    ]
  },
  {
    "id": "pattern-B",
    "shortName": "Pattern B",
    "weeks": [
      "2024:36,38,40,42,44,46,48,50"
    ]
  }
]

Ein weeklyExpression-Objekt kann beispielsweise wie folgt auf das erste Wochenmuster verweisen:

"validWeeks": {
  "refId": "pattern-A"
}

Die wöchentliche Wiederholung findet damit ausschließlich in den für pattern-A definierten Kalenderwochen statt.

Erweiterung der Spezifikation¶

Die OpenT8-Spezifikation kann an bestimmten Stellen um zusätzliche Daten erweitert werden.

Die Eigenschaften der Erweiterungen sind als freie Felder implementiert, denen immer ein x- vorangestellt werden MUSS (z.B. x-external-id). Der Wert kann eine Zeichenfolge, eine Zahl, ein boolescher Wert, Null, ein Objekt oder ein Array sein.

Die Erweiterungen können von den verfügbaren Werkzeugen unterstützt werden oder auch nicht. Idealerweise können diese Werkzeuge erweitert werden, um die gewünschte Unterstützung hinzuzufügen (z.B. bei Open Source-Projekten).

Beispiel:

"buildings": [
  {
    "id": "100",
    "shortName": "HG",
    "longName": "Hauptgebäude",
    "x-postalAddress": "Berliner Weg 42, 30100 Braunschweig",
    "x-website": "https://beispiel.de"
  }
]

Wert	Beschreibung
`person`	Eine Person ist abwesend.
`group`	Eine Gruppe ist abwesend.
`room`	Der Raum steht nicht zur Verfügung.

Wert	Beschreibung
`activity`	Fehlstelle für eine Aktivität
`lesson`	Fehlstelle für eine Unterrichtseinheit
`supervision`	Fehlstelle für eine Aufsicht

Wert	Beschreibung
`activity`	Vertretung durch eine Aktivität
`lesson`	Vertretung durch eine Unterrichtseinheit
`supervision`	Vertretung durch eine Aufsicht