JSON-Schema-Generator

Wofür JSON Schema da ist

JSON Schema ist eine deklarative Art zu beschreiben, wie ein JSON-Dokument aussehen soll: welche Eigenschaften es hat, welche Typen diese Eigenschaften tragen, was erforderlich vs. optional ist und welche Werte gültig sind. Es ist das JSON-Welt-Äquivalent zu XSD für XML oder einer Datenbanktabellen-Definition. Das offizielle Projekt lebt unter json-schema.org.

Wo du es in freier Wildbahn triffst:

• API-Verträge. OpenAPI 3.1 (Release Februar 2021) bettet JSON Schema direkt ein: jeder Request-Body und jeder Response-Body in einer modernen API-Spec wird mit einem JSON-Schema-Fragment beschrieben.
• IDE-Autocomplete und Validierung. Die settings.json von VS Code, die package.json und tsconfig.json deines Projekts, GitHub-Actions-workflow.yml-Dateien, alles wird gegen veröffentlichte JSON Schemas autovervollständigt und gelinted.
• Serverseitige Validierung. Express / Fastify / Spring / Flask / FastAPI / Echo, alle integrieren mit JSON-Schema-Validatoren (AJV, jsonschema, fastjsonschema), um fehlerhafte Request-Bodies abzulehnen, bevor sie auf die Geschäftslogik treffen.
• Code-Generierung. Tools wie quicktype, json-schema-to-typescript und datamodel-code-generator verwandeln ein Schema in Go-Structs, TypeScript-Typen, Python-Dataclasses, Java-POJOs usw. und liefern aus einer einzigen Quelle sprachagnostische Typen.
• Dokumentation. Ein Schema dient gleichzeitig als maschinenlesbare Dokumentation für jede JSON-förmige Daten, die du veröffentlichst.

Die Drafts, denen du in der Praxis begegnest

Die JSON-Schema-Spezifikation wurde als Reihe von Drafts veröffentlicht. Der aktuelle stabile Draft ist 2020-12 (laut offizieller Spec-Seite: «The current version is 2020-12»). Die Drafts, denen du begegnen könntest:

• Draft 4, alt, aber noch in Verwendung; OpenAPI 3.0 verwendete eine erweiterte Untermenge der JSON Schema Specification Wright Draft 00 (manchmal informell Draft 5 genannt), die nahe an, aber nicht identisch mit Draft 4 ist.
• Draft 6, Draft 7, Draft 7 (2018) war jahrelang der dominante Produktions-Draft und ist in Legacy-Tooling immer noch sehr verbreitet.
• Draft 2019-09, erster Draft, der die Jahr-Monat-Kennzeichnungskonvention verwendet; führte $defs neben dem Legacy-Schlüsselwort definitions ein.
• Draft 2020-12, der aktuelle stabile Draft und das, was dieser Generator ausgibt. An OpenAPI 3.1 angeglichen.

Im Zweifel: wähle den Draft, der zu deinem Validator passt. AJV (der populärste JavaScript-Validator) unterstützt mit explizitem Opt-in die Drafts 04, 06, 07, 2019-09 und 2020-12. jsonschema in Python tut dasselbe. Wenn du nicht weißt, was dein Downstream-Konsument will, ist 2020-12 ein sicherer Default für neue Arbeit.

Die eingebauten Typen

JSON Schema beschreibt sieben Basistypen, die den Wertarten von JSON entsprechen:

Kompositions-Schlüsselwörter erlauben das Mischen und Kombinieren: oneOf (genau eines), anyOf (mindestens eines), allOf (alle), not (das Gegenteil). Plus enum für eine endliche Liste erlaubter Werte und const für einen einzigen festen Wert.

Was ein automatisch erzeugtes Schema sagen kann und nicht

Ein Schema aus einem einzigen JSON-Beispiel zu inferieren ist mächtig, aber begrenzt. Der Generator kann erkennen:

• Den Typ jedes Blattwerts (string vs. number vs. boolean vs. array vs. object).
• Die Struktur verschachtelter Objekte und Arrays.
• Die Schlüssel, die im Beispiel auftauchen (und sie als required markieren, falls du das aktivierst).

Es kann nicht erkennen:

• Optionale Felder. Ein Schlüssel in deinem Beispiel könnte in der echten Spec optional sein, aber ein einzelnes Beispiel kann dir nicht sagen, welche. Standardmäßig sieht alles erforderlich aus.
• Format-Hinweise. Der String "2024-04-12" sieht wie ein Datum aus, könnte aber auch ein freies Text-Label sein, das zufällig datumförmig wirkt. Füge format: date von Hand hinzu, wenn das Feld wirklich eines ist.
• Validierungseinschränkungen. Maximale Länge, erlaubte Enum-Werte, Regex-Muster: alles braucht menschlichen Input.
• Dokumentations-Strings. title, description und examples auf jedem Feld verbessern die Developer Experience, brauchen aber Pflege.
• Varianten. Wenn ein Feld je nach Kontext entweder ein String oder eine Number sein kann, wählt ein einzelnes Beispiel eines aus und verpasst das andere. Kombiniere mehrere Beispiele oder nutze oneOf manuell.

Behandle die Ausgabe als zu 70% fertigen Ausgangspunkt. Die wertvollen Ergänzungen (welche Felder tatsächlich erforderlich sind, welche String-Formate gelten, welche Wertbereiche erlaubt sind, was jedes Feld bedeutet) sind der Schritt der menschlichen Pflege.

Zwei subtile Fallen, die man kennen sollte

• format ist in 2020-12 standardmäßig beratend. Das format-annotation-Vokabular markiert format: email als Hinweis, nicht als harte Validierungsregel, sofern dein Validator nicht ausdrücklich auf format-assertion opt-int. Ein String, der nicht zur Email-Regex passt, geht also standardmäßig durch. AJVs strict-Modus und das ajv-formats-Paket fügen vollständige Format-Validierung hinzu; prüfe die Defaults deines Validators, bevor du dich für sicherheitskritischen Input auf Format-Checks verlässt.
• additionalProperties: false kooperiert nicht gut mit allOf. Wenn du Schemas mit allOf für Vererbungs-Style-Validierung komponierst, sieht additionalProperties: false auf einem Zweig keine Eigenschaften, die in Geschwisterzweigen definiert sind, sodass legitime Felder die Validierung nicht bestehen. Der Fix in Draft 2019-09+ ist unevaluatedProperties: false, das kompositionsbewusst ist.

JSON Schema vs. Zod / Joi / Yup vs. TypeScript-Typen

Mehrere Technologien überschneiden sich mit der Rolle von JSON Schema; jede hat einen anderen Sweet Spot:

• JSON Schema. Deklaratives JSON, Laufzeit-Validierung, sprachagnostisch. Gewinnt, wo API-Verträge Sprachgrenzen überschreiten (z. B. ein Go-Server, eine Python-Datenpipeline und ein TypeScript-Frontend, die alle dieselbe API konsumieren).
• TypeScript-Typen. Nur zur Compile-Zeit. Wunderschön für In-Process-Typsicherheit innerhalb einer TS-Codebase, aber sie verschwinden zur Laufzeit und bieten keine Validierung von eingehendem JSON. Tools wie json-schema-to-typescript generieren Typen aus einem Schema für das Beste aus beiden Welten.
• Zod / Joi / Yup. Code-First-Laufzeit-Validierung in JavaScript / TypeScript, mit eingebauter TypeScript-Inferenz. Eine Sprache, aber innerhalb dieser Sprache hervorragende Developer Experience. Schemas sind JS-Objekte, kein portables JSON.
• Pydantic / Marshmallow. Die Python-Pendants: klassenbasierte Laufzeit-Validierung mit Python-Type-Hints.

Wenn dein Schema von mehreren Sprachen oder von Tools (IDEs, OpenAPI-Tooling, Code-Generatoren) konsumiert werden muss, ist JSON Schema das richtige Zuhause. Wenn du innerhalb einer einzigen Sprache bleibst, ist die sprach-eigene Option meist angenehmer zu schreiben.

Häufige Anwendungsfälle

• Eine OpenAPI-Spec bootstrappen. Füge eine echte API-Antwort ein, generiere das Schema, lege es in deine components.schemas.
• TypeScript-/Go-/Python-Typen generieren via quicktype oder Ähnliches und so aus einer einzigen Quelle sprachagnostische Typen liefern.
• Untrusted Input validieren auf einem Server-Endpoint mit AJV / jsonschema / Pydantic.
• IDE-Autocomplete schreiben für ein eigenes Konfigurationsformat. VS Code, JetBrains-IDEs und andere lesen JSON Schemas, um JSON-Datei-Autocomplete zu betreiben.
• Die Form einer Konfigurationsdatei dokumentieren für Downstream-Konsumenten.
• Zwischen Datenformaten migrieren. Ein aus einer Quelle generiertes JSON Schema kann Validierung, Transformation oder Dokumentation Downstream antreiben.

Häufige Fehler

1. Das automatisch generierte Schema als finale Spec behandeln. Es ist ein Ausgangspunkt. Füge Format-Hinweise hinzu, markiere wirklich-optionale Felder, ergänze Dokumentation, lege Wertbereiche fest.
2. Die $schema-Deklaration weglassen. Validatoren benutzen sie, um zu wissen, welcher Draft anzuwenden ist. Setze sie immer an den Anfang des Schemas.
3. required als Pro-Eigenschaft-Attribut behandeln. Anders als bei XSD oder Mongoose-Schemas ist das required in JSON Schema ein Array auf Eltern-Objekt-Ebene, das die Namen der erforderlichen Eigenschaften auflistet.
4. additionalProperties: false vergessen, wenn du strenge Validierung willst. Der Default ist true, was bedeutet, dass unbekannte Schlüssel stillschweigend erlaubt sind.
5. enum mit examples verwechseln. enum = die Liste erlaubter Werte (Validierung). examples = Beispielwerte, nur für Dokumentation (kein Validierungseffekt).
6. Annehmen, format werde durchgesetzt. Im Draft 2020-12 ist es standardmäßig eine Annotation, keine Assertion; deine Email-Regex läuft nicht, es sei denn, du opt-inst.
7. Optionalität aus einem einzigen Beispiel ableiten. Jeder Schlüssel in deinem Beispiel wird standardmäßig required. Echte Specs haben fast immer optionale Felder; entferne sie als Teil der Pflege aus dem required-Array.

Weitere häufig gestellte Fragen

Funktioniert das Schema mit OpenAPI 3.1?

Ja. OpenAPI 3.1 (veröffentlicht im Februar 2021) hat seine Schema-Sprache vollständig an JSON Schema Draft 2020-12 angeglichen, was dieser Generator ausgibt. Lege das Schema in components.schemas in deinem OpenAPI-Dokument ab und referenziere es per $ref. Älteres OpenAPI 3.0 verwendete eine frühere Untermenge; du musst eventuell anpassen, falls du auf 3.0 zielst.

Kann ich aus diesem Schema Typen in meiner Sprache generieren?

Ja. quicktype generiert TypeScript, Go, Python, Java, C#, Swift, Kotlin, Rust, Elm und andere aus einem JSON Schema. json-schema-to-typescript ist eine JS-spezifische Alternative. Die meisten modernen Sprachen haben mindestens ein Schema-zu-Typen-Tool; das generierte Schema funktioniert für alle als Eingabe.

Was ist der Unterschied zwischen $defs und definitions?

Beide sind Orte, an denen wiederverwendbare Sub-Schemas abgelegt werden, die du anderswo im Dokument $referenzieren kannst. definitions ist der Legacy-Name, in den Drafts 04, 06 und 07 verwendet. $defs ist der aktuelle Name, in Draft 2019-09 eingeführt und in 2020-12 fortgeführt. Funktional gleichwertig, aber benutze $defs für neue Arbeit.

Wird mein JSON irgendwo hingeschickt?

Nein. Die Schema-Generierung läuft komplett in deinem Browser. Das eingefügte JSON wird lokal geparst, durchlaufen und als Schema in der Ausgabe-Textarea ausgegeben. Nichts wird auf einen Server hochgeladen, geloggt oder nach dem Schließen des Tabs aufbewahrt. Das ist wichtig, weil JSON-Beispiele oft echte Daten enthalten (Kundendatensätze, interne API-Antworten, Mitarbeiterinfos), die du nicht durch einen Drittanbieter laufen lassen willst.

Warum hat das Schema meines Arrays nur das erste Element beschrieben?

Inferenz aus einem einzelnen Beispiel behandelt Arrays als homogen: Sie schaut auf das erste Element und nimmt an, dass der Rest passt. Wenn dein echtes Array unterschiedliche Formen halten kann, musst du die items als { "oneOf": [...] } von Hand schreiben. Oder den Generator auf jede Variante separat laufen lassen und die Schemas kombinieren.

Soll ich überhaupt einen Generator nutzen oder das Schema von Hand schreiben?

Für ein kleines Schema, das du End-zu-End kontrollierst, lehrt dich Handschreiben die Spec schneller. Für eine große API-Antwort mit Dutzenden verschachtelten Objekten bringt dich der Generator in Sekunden zu einem Entwurf, und du verbringst die gesparte Zeit mit dem Pflegen von Einschränkungen, Beschreibungen und required-Arrays. Die meisten arbeitenden Entwickler tun beides: generieren, dann pflegen.