Das Dateiformat

Format studynow · Version 3 · Stand 2026-09-23

Diese Spezifikation ist normativ. Die Schlüsselwörter MUSS, DARF NICHT, SOLL und KANN sind im Sinne von RFC 2119 zu lesen. Eine Einführung für Ersteller steht in README.md.

1 Datei

• Eine Datei ist ein JSON-Dokument (RFC 8259) in UTF-8.
• Die Dateiendung MUSS .studynow lauten.
• Der Inhaltstyp SOLL application/vnd.studynow+json sein; application/json ist zulässig.
• Eine Datei beschreibt genau ein Profil (Abschnitt 3).

2 Kopf

Jede Datei beginnt mit denselben drei Feldern.

Eine App MUSS eine Datei mit einer ihr unbekannten version ablehnen, statt sie teilweise zu lesen.

Version 2 ist rein ergänzend. Jede Datei der Version 1 ist eine gültige Datei der Version 2; alle in Version 2 hinzugekommenen Felder sind freiwillig. Wer eine Datei schreibt, die ohne die neuen Felder auskommt, SOLL weiter "version": 1 angeben — dann lesen auch ältere Apps sie. Neu sind: Lehrende und Räume je Veranstaltung, die Terminarten seminar, labor und muendlichePruefung, das Merkmal zaehltAlsPruefung, die Uhrzeit an Fristen, die Farbe der Veranstaltung, der Serienbezug am Einzeltermin und das Profil semestervorlage. Unbekannte Felder an beliebiger Stelle MUSS eine App ignorieren; Ersteller DÜRFEN NICHT darauf bauen, dass sie ausgewertet werden.

Version 3 ist ebenfalls ergänzend. Neu ist allein das Profil schulvorlage (Abschnitt 6b). Die Hochschulprofile sind unverändert; wer eines davon schreibt, SOLL weiter "version": 2 bzw. 1 angeben. Eine Datei mit "profil": "schulvorlage" MUSS "version": 3 tragen.

3 Profile

Granularität ist ein Studiengang je Datei — nicht eine Datei je Hochschule.

4 Wertformen

Zeitangaben sind Ortszeit der Hochschule. Ein Zeitraum aus beginn und ende schließt beide Tage ein; beginn DARF NICHT nach ende liegen.

Kennungen

Jedes Element einer Liste und das Semester tragen eine id.

• Eine id MUSS innerhalb ihrer Liste eindeutig sein.
• Eine id MUSS über alle Fassungen der Datei stabil bleiben. Sie verbindet ein Element beim Neuladen mit sich selbst (Abschnitt 7). Eine geänderte id bedeutet: altes Element entfällt, neues kommt hinzu.

5 Profil studiengangsrahmen

5.1 Oberste Ebene

studiengang zusammen mit semester.id identifiziert eine Datei. Eine App MUSS eine zweite Datei mit gleichem Paar als neue Fassung derselben Datei behandeln, nicht als weiteres Semester.

5.2 semester

Die Vorlesungszeit ist die Referenz für alle Terminserien: Serien laufen während der Vorlesungszeit, nicht während der Semesterzeit.

5.3 vorlesungsfrei[]

Vorlesungsfreie Zeiten schneiden Termine aus Serien heraus.

5.4 phasen[] — An- und Abmeldephasen (veraltet)

Seit App-Version 6.10.1 sind An- und Abmeldephasen Semesterfristen (5.6): art anmeldung oder abmeldung, das Ende der Phase als abgabe, ihr Beginn als start. Neue Dateien SOLLEN fristen verwenden. Eine App MUSS phasen weiter lesen und legt je Phase eine Semesterfrist an – bei beides zwei, die Abmeldung mit der Kennung <id>-abmeldung. Die Bezeichnung ist bezeichnung oder, wenn sie fehlt, die Art im Plural („Prüfungen“, „Studienleistungen“ …).

Mehrere Phasen derselben Art sind zulässig.

5.5 termine[] — semesterweite Termine

Für Hochschulweites mit Ort und Uhrzeit: Begrüßung, Informationsveranstaltung.

praktikum und labor sind seit Version 2 getrennt. Der Wert praktikumLabor steht für die frühere zusammengefasste Art; er DARF gelesen, SOLL aber nicht mehr geschrieben werden.

5.6 fristen[] — semesterweite Fristen

Für Hochschulweites mit Abgabezeitpunkt: Rückmeldung, BAföG-Nachweis, Prüfungsan- und -abmeldung.

6 Profil lehrveranstaltungen

Alle Lehrveranstaltungen, die ein Studiengang in einem Semester anbietet. Die Studierenden wählen daraus aus, was sie belegen; eine App DARF NICHT ungefragt alle anlegen.

6.1 Oberste Ebene

studiengang und semester verbinden die Liste mit einem importierten Studiengangsrahmen. Gibt es keinen passenden, SOLL die App das Zielsemester erfragen, statt die Liste abzulehnen.

6.2 veranstaltungen[]

Termine SOLLEN als Einzeltermine geliefert werden. Wo das Campussystem nur Regeln kennt, sind Serien zulässig; beides DARF in einer Veranstaltung gemischt vorkommen. Raum und Dozent sind nicht Teil des Formats — sie pflegen die Studierenden selbst.

6.2a Lehrende, Räume und Farbe (seit Version 2)

Alle drei stehen an der Veranstaltung und sind freiwillig.

art eines Raums: vorlesungsraum · uebungsraum · labor · pruefungsraum · sonstiges.

Eine unbekannte farbe DARF die App durch eine eigene ersetzen; sie MUSS die Datei deswegen nicht ablehnen. Einen Hex-Wert übernimmt die App als eigene Farbe; die Töne für hellen und dunklen Hintergrund leitet sie selbst ab. Die Namen der festen Farben: tomate · tuerkis · mandarine · indigo · gras · fuchsie · himmel · senf · pflaume · stein.

6.3 eigenschaften

Alle Felder sind Wahrheitswerte (true/false) und optional.

Eine App SOLL eine Eigenschaft auch dann setzen, wenn sie aus dem Inhalt folgt (eine Serie der Art uebung, zentraluebung oder tutorium bedeutet Übungsgruppen). Die ausdrückliche Angabe ist für das Gegenteil da: "pruefung": true ohne Klausurtermin sagt „der Termin steht noch aus", und die App erinnert daran.

6.4 serien[] — Terminserien

Eine Serie MUSS wochentag oder von angeben. Die App rechnet sie beim Import in Einzeltermine um:

• mit wochentag: erster Termin ist der erste solche Wochentag ab von, ohne von ab Beginn der Vorlesungszeit;
• ohne wochentag: von ist der erste Termin, sein Wochentag gilt.
• Letzter möglicher Termin ist bis, ohne bis das Ende der Vorlesungszeit.
• Termine in vorlesungsfreien Zeiten entfallen; der Rhythmus läuft dabei weiter.

Für mehrere Termine pro Woche werden mehrere Serien angegeben.

6.5 termine[] — Einzeltermine

Wie 5.5, zusätzlich mit dem optionalen Wahrheitswert anwesenheitspflicht. Einzeltermine werden auch in vorlesungsfreien Zeiten angelegt — eine Klausur liegt dort in der Regel.

Seit Version 2 zusätzlich:

serie MUSS auf eine Serie derselben Veranstaltung zeigen; ein Verweis ins Leere MUSS die Datei ungültig machen. Nennt eine Datei zu einer Serie mindestens einen Termin, MUSS die App genau diese Termine anlegen und das aus der Regel errechnete Raster verwerfen. So überleben Verschiebungen, Ersatztermine und Ausfälle den Weg durch eine Datei. Nennt sie keine, gilt allein die Regel aus 6.4.

6.6 fristen[] — Einzelfristen

Wie 5.6.

6.7 fristserien[]

Fristen entfallen nicht in vorlesungsfreien Zeiten.

6.8 Erneutes Öffnen

Eine Liste DARF mehrmals geöffnet werden. Veranstaltungen, die mit derselben id schon im Semester stehen, MUSS die App als vorhanden kennzeichnen und DARF sie NICHT ein zweites Mal anlegen. Änderungen der Datei an bereits importierten Veranstaltungen übernimmt die App in dieser Version nicht; die Regeln aus Abschnitt 7 gelten nur für den Studiengangsrahmen.

6a Profil semestervorlage (seit Version 2)

Ein ganzes Semester zum Weitergeben: Wer es einmal eingepflegt hat, gibt die Struktur an andere weiter, statt dass jede Person sie abtippt. Eine Vorlage entsteht typischerweise in der App selbst („Semester als Vorlage teilen"), nicht im Studienbüro.

6a.1 Aufbau

semester.id ist die Kennung der Vorlage. Sie MUSS über alle Fassungen derselben Vorlage gleich bleiben und DARF NICHT für eine andere Vorlage wiederverwendet werden: Daran erkennt eine App, dass jemand dieselbe Vorlage ein zweites Mal öffnet.

6a.2 Was nicht hineingehört

Eine Vorlage ist keine Sicherung. Sie DARF NICHT enthalten: Teilnahme, Bewertungen, Erledigungsstände und -zeitpunkte, Erfolge, persönliche Notizen, individuelle Erinnerungen oder Geräteeinstellungen. Wer eine Datei weitergibt, gibt Struktur weiter, nicht sein Studium.

6a.3 Import

• Ein Import legt immer ein neues Semester an. Eine App DARF NICHT still überschreiben oder mit einem laufenden Semester zusammenführen.
• Ist schon ein Semester mit derselben Vorlagenkennung vorhanden — auch das, aus dem die Datei stammt —, MUSS die App vor der Dublette warnen und Abbrechen sowie bewusstes Anlegen einer Kopie anbieten.
• Die Prüfung nach Abschnitt 8 läuft vor jeder Änderung. Eine ungültige Datei MUSS den Bestand unverändert lassen; gespeichert wird vollständig oder gar nicht.
• Abschnitt 7 (Neuladen) gilt für dieses Profil nicht: Eine Vorlage ist ein Ausgangspunkt, keine Quelle, die weiter gepflegt wird.

6b Profil schulvorlage (seit Version 3)

Eine Klasse (Klassen 5–10) oder ein Kursangebot der Oberstufe für ein Halbjahr. Eine Lehrkraft richtet die Klasse in der App ein und teilt sie („Schulplan als Vorlage teilen“); die Lernenden wählen beim Öffnen aus, was für sie gilt. Ein maschinenlesbares Schema steht in schulvorlage.schema.json, Beispiele in beispiele/schulvorlage-7b.studynow und beispiele/schulvorlage-q11.studynow.

6b.1 Aufbau

6b.2 halbjahr

name (Text), schuljahr (Text, etwa 2026/27), nummer (1 oder 2), beginn und ende (Datum), dazu freiwillig klasse (etwa 7b), jahrgang (Zahl) und phase (etwa Q1.1). Bezeichnungen wie „Q1.1“ sind Beschriftungen; ihre Daten gelten, wie sie in der Datei stehen.

6b.3 zeitraster

stunden[]: je Stunde nr (ganze Zahl ab 1), beginn, ende (Uhrzeit; ende nach beginn). Freiwillig abweichungen: ein Objekt mit Wochentagen "1" (Montag) bis "7" als Schlüssel und je einer eigenen Stundenliste – etwa ein kürzerer Freitag.

6b.4 abWochen

anker (Datum), ankerWoche (A oder B), ferienZaehlen (Wahrheitswert) und wochen: ein Objekt mit dem Montag jeder Woche als Schlüssel und A oder B als Wert. Maßgeblich ist diese Liste, nicht eine Regel – eine App DARF den Rhythmus nicht neu berechnen.

Seit App-Version 6.10.2 DARF art angegeben sein: ab (Standard) oder kw für gerade und ungerade Kalenderwochen. Bei kw ist A jede ungerade, B jede gerade Kalenderwoche; die Liste wochen MUSS trotzdem stehen und dem entsprechen. Die App beschriftet die Wochen dann mit „ungerade“ und „gerade“.

6b.5 faecher[]

id, name, freiwillig kurzform, farbe, kurscode, niveau (etwa gA, eA, GK, LK), wahlgruppe, lehrkraft, raum. Fächer mit derselben wahlgruppe sind Alternativen: Beim Import wählt die Person höchstens eines davon. lehrkraft DARF NUR enthalten sein, wenn die Lehrkraft der Weitergabe zugestimmt hat.

6b.6 unterricht[]

id, fach (Verweis auf faecher[].id), wochentag (1–7), stunde (Verweis auf eine Stunde des Rasters an diesem Wochentag), freiwillig woche (A oder B; erfordert abWochen) und raum.

6b.7 Was nicht hineingehört

Wie 6a.2, und ausdrücklich: keine Aufgaben, keine Rückblicke, keine Erledigt-Stände, keine Erinnerungseinstellungen, keine Namen von Lernenden, keine Zugangsdaten oder Abo-Adressen.

6b.8 Import

• Ein Import legt immer ein neues Halbjahr an, nur mit den gewählten Fächern. In der Klasse sind die Fächer ohne Wahlgruppe vorgewählt, aus jeder Wahlgruppe wählt die Person eines oder keines. In der Oberstufe ist nichts vorgewählt.
• Bei gleicher Vorlagenkennung MUSS die App vor der Dublette warnen.
• Eine ungültige Datei ändert nichts; gespeichert wird vollständig oder gar nicht. Neuladen (Abschnitt 7) gilt nicht.

6c Kalenderdateien und Tabellen

Neben .studynow nimmt die App im Schulbereich zwei verbreitete Formate an. Sie sind nicht Teil dieses Formats, folgen aber denselben Regeln: Vorschau vor jeder Änderung, alles oder nichts, und was in einer Datei fehlt, wird nicht gelöscht.

Kalenderdatei (ICS, RFC 5545). Übernommen werden VEVENT mit SUMMARY, DTSTART, DTEND/DURATION, LOCATION, STATUS, Wiederholungen (RRULE, RDATE, EXDATE) und Ausnahmen (RECURRENCE-ID) – nur im Zeitraum des Halbjahres. Die Identität eines Termins ist UID plus ursprüngliches Vorkommen; eine verlegte Stunde bleibt derselbe Termin. DTEND ist exklusiv. STATUS:CANCELLED ist ein Ausfall. Teilnehmer, Alarme und Anhänge werden nicht übernommen.

Tabelle (CSV). UTF-8, Semikolon oder Komma, erste Zeile mit Spaltennamen. Zwei Modi, ausdrücklich gewählt:

Datum als 2026-09-24 oder 24.09.2026; mehrdeutige Angaben wie 03/04/26 werden abgelehnt, nicht geraten. Ohne id-Spalte ist nur eine einmalige Übernahme möglich. Beispiele: beispiele/stundenplan-datiert.csv, beispiele/stundenplan-wochenplan.csv, beispiele/stundenplan.ics.

Erneuter Import. Mit stabilen Kennungen gleicht die App ab: Was nur die Quelle ändert, wird übernommen; was nur die Person geändert hat, bleibt; wo beide Verschiedenes sagen, fragt die App mit beiden Werten.

7 Neuladen

Diese Regeln richten sich an Implementierer; sie erklären Erstellern, warum Kennungen stabil bleiben müssen.

Abschnitt 7 gilt für das Profil studiengangsrahmen.

Eine App SOLL die zuletzt importierte Datei unverändert als Original aufbewahren. Beim Neuladen vergleicht sie je Feld drei Stände: Original, lokalen Stand und neue Datei.

Stimmen lokaler Wert und neuer Wert überein, entfällt die Rückfrage.

Für Elemente gilt entsprechend:

Nach dem Neuladen wird die neue Datei zum Original.

8 Fehler

Eine App MUSS eine ungültige Datei vollständig ablehnen und DARF dabei keine Daten anlegen oder ändern. Sie SOLL alle Verstöße auf einmal melden, jeweils mit der Stelle in der Datei (etwa phasen[2].beginn).

9 Übergabe an die App

Der Server MUSS die Datei über HTTPS ohne Anmeldung ausliefern. Für die Browser-Fassung der App MUSS er Access-Control-Allow-Origin setzen.