Zum Inhalt springen
MILES Knowledge Base

Schema-Validierung

GraphQL beschreibt bereits die allermeisten Felder im Detail. Bei komplexen JSON-Feldern stößt es allerdings an seine Grenzen. Deswegen beschreiben wir diese mit JSON Schema und prüfen die Korrektheit der Daten bei jedem Schreibzugriff.

Jedes Schema, gegen das wir prüfen, ist über unseren Katalog auffindbar:

https://api-prod.mileslearning.net/schemas

Grundsätzlich gilt, dass ungültige Daten mit einem JSON_INVALID-Fehler abgelehnt werden. Details zu den einzelnen Validierungsfehlern sind in der Antwort enthalten, damit die Korrektur leichter fällt.

Übungsinhalte

Abschnitt betitelt „Übungsinhalte“

Zu jedem Übungstyp gehören zwei Schemas:

  • exercise/<TYPE>.json
    beschreibt die Struktur und wird beim Aufruf von createExercise und updateExercise geprüft.

  • exercise/<TYPE>.complete.json
    beschreibt, was zusätzlich notwendig ist, um eine Übung veröffentlichen zu können. Exercise.valid meldet dann das Ergebnis dieser Prüfung.

Manche Regeln lassen sich auch in JSON Schema nicht ausdrücken, etwa dass eine Antwort auf einen vorhandenen Key verweisen muss. Auf solche zusätzlichen Regeln weisen wir im Schema in der Beschreibung des betroffenen Feldes hin.

Vor dem Schreiben prüfen

Abschnitt betitelt „Vor dem Schreiben prüfen“

Um API-Fehlern von vornherein vorzubeugen, empfehlen wir, einen Validator einzurichten. Zum Beispiel:

Änderungen an den Schemas kündigen wir wie gewohnt im API-Changelog an.