TBA3-Auswertungsschnittstelle: Endpunkt-Referenz

Diese Referenz richtet sich an Frontend- und Backend-Entwickler:innen. Sie beschreibt alle Endpunkte, die die Spec definiert, sowie die Konventionen, die auf diesen Endpunkten sinnvoll sind.

Grundbegriffe (Value-Group, 3-Schichten-Architektur) sind in Konzepte und Architektur erklärt.

Sprachkonvention#

Die Schnittstelle ist in Englisch definiert: Feldnamen, Endpunkte und Schlüssel sind englisch (z.B. competenceLevels, descriptiveStatistics, frequency).

Werte werden üblicherweise in Deutsch übergeben, da sie aus deutschsprachigen Systemen stammen (z.B. "name": "Regelstandard", "name": "Leseverstehen"). Werte, deren Ausprägungen gemeinsam als Konvention definiert sind, können auch Englisch sein (z.B. "value": "male" bei Covariates).

Was die Spec definiert#

Die Spec definiert 9 Endpunkte: 3 Ebenen × 3 Datentypen. Jeder Endpunkt gibt ein Array von Value-Groups zurück. Was eine einzelne Value-Group repräsentiert (eine Lerngruppe, ein:e SuS, eine Schule, ein Vergleichswert …), hängt von der Implementierung des Backends bzw. dem Query-Parameter type ab.

Kompetenzstufenverteilung (/competence-levels)#

Jede Value-Group enthält ein competenceLevels[]-Array. Jeder Eintrag beschreibt eine Kompetenzstufe (z.B. „Regelstandard") mit zugehöriger deskriptiver Statistik (Häufigkeit, Mittelwert, Gesamtzahl).

Verhalten bei type=student: Auf Schülerebene wird pro SuS nur die erreichte Kompetenzstufe zurückgegeben (nicht alle Stufen mit frequency=0). Das competenceLevels[]-Array enthält dann in der Regel genau einen Eintrag.

Lösungshäufigkeiten (/items)#

Jede Value-Group enthält ein items[]-Array. Jeder Eintrag beschreibt ein einzelnes Item (Testaufgabe) mit Lösungshäufigkeit und optionalen Item-Parametern.

Aggregationen (/aggregations)#

Jede Value-Group enthält ein aggregations[]-Array. Jeder Eintrag beschreibt eine Aggregation nach einem bestimmten Typ (z.B. nach Kompetenz oder Geschlecht) mit deskriptiver Statistik. Welche Aggregationsarten verfügbar sind, steuert der aggregation-Parameter (→ Query-Parameter).

Response-Inhalte einer Value-Group#

Zur Orientierung die Grundstruktur einer Value-Group:

Value-Group
├── id           (optional) — Eindeutige Kennung
├── name         (Pflicht)  — Bezeichnung, z.B. "Klasse 8a"
├── type         (Pflicht)  — Typ einer Value Group
├── domain       (optional)
│   ├── id       (optional)
│   └── name     (Pflicht) — z.B. "Leseverstehen"
├── subject      (optional)
│   ├── id       (optional)
│   └── name     (Pflicht) — z.B. "Deutsch"
├── covariates   (optional) — Kovariaten der Value-Group (Geschlecht, Sprache, ...)
├── properties   (optional) — Freie Key-Value-Metadaten
└── ... Ergebnisdaten (je nach Endpunkt)

Neben den endpunktspezifischen Ergebnisdaten (competenceLevels, items, aggregations) trägt jede Value-Group optionale Kontextfelder. Konzeptionell sind alle diese Felder Metadaten über die Value-Group. subject und domain sind bewusst als eigene Felder modelliert (nicht als Properties), weil Berichte sehr häufig nach Fach und Domäne gruppieren — sie sind strukturelle Metadaten. covariates sind typisierte Merkmale der Personen in der Gruppe. properties sind komplett freie Key-Value-Paare für alles andere.

type: Typ einer Value-Group#

Die Value-Group hat ein type-Feld, das die Granularität beschreibt. So kann ein Berichtselement erkennen, was eine Value-Group repräsentiert — auch ohne den ursprünglichen Request zu kennen.

subject und domain: Fach und Domäne#

subject und domain sind eigene Response-Felder (nicht Properties), weil in Berichten fast immer nach Fach und Domäne gruppiert wird.

subject ist ein Objekt mit id (optional) und name (Pflicht), z.B. { name: "Deutsch" }. domain ist ebenfalls ein Objekt mit id (optional) und name (Pflicht). Der name enthält die lange Beschreibung der Domäne, z.B. { name: "Leseverstehen" }.

Für den Query-Parameter domain werden Kürzel für Teilbereiche eines Fachs verwendet. Die Kürzel entsprechen den Domänen-Bezeichnungen aus den Itemkennwerttabellen des IQB (Kompetenzstufenmodelle).

Wichtig: Query-Kürzel vs. Response-Objekt. Die Kürzel in der Tabelle oben sind Werte für den domain-Query-Parameter (z.B. ?domain=rs). Das domain-Feld in der Response ist dagegen ein Objekt mit der langen Beschreibung, z.B. { name: "Rechtschreibung" }. Das Backend setzt die lange Beschreibung kontextabhängig — sie kann je nach Jahrgangsstufe variieren (z.B. rs = "Rechtschreibung" in der Grundschule, "Orthografie" in der Sek I).

Gruppierung nach Domäne: Ob die Response nach Domäne gruppiert wird (eine Value-Group je Domäne) oder flach zurückkommt, hängt vom Endpunkt und Anwendungsfall ab. Details und Empfehlungen im Rezept: Gruppierung nach Domäne.

Details und Beispiele zum Sonderfall Mathe in Rezept: Leitideen in Mathematik beschrieben.

covariates: Merkmale Personen(gruppen)#

Array von typisierten Merkmalen auf einer Value-Group. Jede Covariate hat type, label, value.

Vordefinierte Typen:

Weitere, eigene Kovariaten können im selben Schema ergänzt werden. Ein Rezept, wie man mit Kovariaten auf anderen Ebenen umgehen kann findet sich in Umgang mit Kovariaten auf Schüler- und Gruppenebene.

properties: Freie Key-Value-Metadaten#

Komplett offene Key-Value-Paare (key, value) für systemspezifische Metadaten über die Value-Group selbst.

Bekannte Beispiele:

Abgrenzung: Covariates vs. Properties#

Faustregel: Zusammensetzung der Personengruppe → Covariates. Kontext der Erhebung → Properties.

Beispiel-Response: Kompetenzstufenverteilung mit Vergleichsgruppe#

GET /groups/3a-deutsch/competence-levels?comparison=3b-deutsch

[
  {
    "name": "Klasse 3a",
    "type": "group",
    "domain": { "name": "Leseverstehen" },
    "subject": { "name": "Deutsch" },
    "competenceLevels": [
      {
        "nameShort": "II",
        "name": "Mindeststandard",
        "descriptiveStatistics": { "frequency": 5, "total": 20, "mean": 0.25 }
      },
      {
        "nameShort": "III",
        "name": "Regelstandard",
        "descriptiveStatistics": { "frequency": 10, "total": 20, "mean": 0.50 }
      },
      {
        "nameShort": "IV",
        "name": "Optimalstandard",
        "descriptiveStatistics": { "frequency": 5, "total": 20, "mean": 0.25 }
      }
    ]
  },
  {
    "name": "Klasse 3b",
    "type": "group",
    "domain": { "name": "Leseverstehen" },
    "subject": { "name": "Deutsch" },
    "competenceLevels": [
      {
        "nameShort": "II",
        "name": "Mindeststandard",
        "descriptiveStatistics": { "frequency": 8, "total": 22, "mean": 0.36 }
      },
      {
        "nameShort": "III",
        "name": "Regelstandard",
        "descriptiveStatistics": { "frequency": 9, "total": 22, "mean": 0.41 }
      },
      {
        "nameShort": "IV",
        "name": "Optimalstandard",
        "descriptiveStatistics": { "frequency": 5, "total": 22, "mean": 0.23 }
      }
    ]
  }
]

Die erste Value-Group enthält die Ergebnisse der angefragten Lerngruppe (3a), die zweite die Vergleichsgruppe (3b). Beide tragen domain und subject als Objekte mit name-Feld.

Query-Parameter: Vorgeschlagene Konventionen#

Die Spec definiert alle Query-Parameter als freie Strings. Die folgenden Konventionen sind ein Vorschlag. Jedes Backend kann eigene Werte einführen. Ein Backend muss keine dieser Konventionen übernehmen, sofern es Bericht und Frontend entsprechend dokumentiert.

Die Query-Parameter nutzen häufig dieselben Werte wie die Response-Felder, erweitern sie aber um Kombinierbarkeit (kommasepariert).

type: Granularität steuern#

Der type-Parameter bestimmt, welche Art von Value-Groups in der Antwort enthalten sind. Die einzelnen Werte sind unter Response-Inhalte → type beschrieben.

Mehrere Werte können kommasepariert übergeben werden. Dann liefert der Endpunkt Value-Groups für jede der kombinierten Granularitätsstufen in einer einzigen Antwort.

Ohne type-Parameter entscheidet das Backend, welche Granularität es standardmäßig liefert.

comparison: Vergleichswerte#

Spec = freier String. Die Werte und ihre Bedeutung definiert das Backend, nicht die Spec.

Der comparison-Parameter steuert, welche Vergleichs-Value-Groups zusätzlich zu den primären Ergebnissen zurückgeliefert werden. Mehrere Werte sind kommasepariert kombinierbar.

Vorgeschlagene Syntax: Präfix typ-id oder nur wert, kommasepariert — z.B. comparison=group-3b,group-3c,state-average. Die Syntax ist im Backend leicht zu parsen und lässt beliebige Kombinationen zu.

Faustregel: Wenn nur der type angegeben wird, entscheidet in der Regel das Backend, welche Vergleichsgruppen geliefert werden. Wenn konkrete Vergleichsgruppen erwünscht sind, werden diese mit type-<id> referenziert.

Vorgeschlagene Comparison-Typen#

Die Comparison-Typen leiten sich aus den type-Werten ab: Was als type in der Response existiert, ergibt in der Regel auch als Vergleichsgruppe Sinn.

Jeder Bericht kann darüber hinaus eigene Werte einführen, z.B. für besondere Vergleichsgruppen oder Shortcuts, die mehrere Vergleichsgruppen bündeln:

Beispiele nach Ebene#

Lerngruppen-Ebene (/groups/{id}/…):

Schul-Ebene (/schools/{id}/…):

Landes-Ebene (/states/{id}/…):

Hinweis zum Mock-Server: Der Mock-Server akzeptiert aktuell einfache kommaseparierte IDs ohne Typ-Präfix (z.B. comparison=3b-deutsch).

Abgrenzung: comparison liefert Werte für andere Gruppen (z.B. Parallelklasse, Landesmittelwert). aggregation liefert andere Sichten auf dieselbe Gruppe (z.B. aufgeschlüsselt nach Kompetenz oder Geschlecht).

aggregation: Aggregationsarten#

Spec = freier String. Welche Aggregationsarten ein Backend unterstützt, ist nicht durch die Spec vorgegeben.

Der aggregation-Parameter ist nur für den /aggregations-Endpunkt relevant. Er bestimmt, nach welchen Dimensionen die Ergebnisse aufgeschlüsselt werden.

Mehrere Werte können kommasepariert kombiniert werden: aggregation=competence,gender

Mock-Server-Beispiele:

• /groups/3a-deutsch/aggregations?aggregation=competence
• /groups/3a-deutsch/aggregations?aggregation=gender

domain: Domäne filtern#

Spec = freier String. Der Parameter ist in api/components/parameters.yml definiert, aber noch nicht an Endpunkte gebunden.

Der domain-Parameter filtert die Ergebnisse nach Domäne. Ohne diesen Parameter liefert das Backend Ergebnisse über alle Domänen. Die Werte und Kürzel sind unter Response-Inhalte → subject und domain beschrieben.

Das Fachkürzel ist ein sinnvoller Shortcut: domain=rs,le ist inhaltlich gleich zu domain=de, wenn in einem Jahr z.B. die Domänen Orthografie und Leseverstehen getestet werden.

Hinweis zum Mock-Server: Der Mock-Server liefert domain-Felder auf Value-Groups zurück, hat aber keinen serverseitigen Filter implementiert — der Parameter wird ignoriert.

Fehlerverhalten#

501 Not Implemented ist die vereinbarte Konvention, wenn ein Backend einen Parameter-Wert prinzipiell nicht unterstützt. Der Response-Body enthält eine erklärende Nachricht. Damit kann ein Frontend zwischen "keine Daten vorhanden" (200 + leeres Array) und "nicht unterstützt" (501) unterscheiden.