JSON-Validator-Glossar

Container für wiederverwendbare Schema-Definitionen (früher: definitions).

In Draft 2019-09 wurde definitions zu $defs umbenannt - semantisch identisch. Konvention: lokale, im selben File referenzierte Schemas in $defs ablegen, dann per { $ref: "#/$defs/Name" } referenzieren. Hilft DRY-Prinzip einzuhalten und Schemas lesbar zu halten.

Verwandt: $ref,$schema

JSON-Pointer-Referenz zu einem Sub-Schema (im selben oder externen Dokument).

$ref erlaubt es Schema-Definitionen wiederzuverwenden. Beispiel: { "$ref": "#/$defs/Address" } verweist auf eine Definition im selben Dokument. Externe Refs sind auch möglich: "https://example.com/schemas/user.json". Ajv löst $refs zur Compile-Zeit auf.

Verwandt: $defs,JSON Pointer

Identifier-Header: welche Schema-Draft-Version gilt für dieses Dokument.

In Draft 2020-12: { "$schema": "https://json-schema.org/draft/2020-12/schema" }. Validator wählt anhand dieser URL die richtige Spec-Interpretation. Fehlt $schema, fällt der Validator auf seinen Default-Draft zurück - sollte aber immer explizit gesetzt sein.

Verwandt: Draft 2020-12

Steuert ob nicht-deklarierte Felder im Objekt erlaubt sind.

additionalProperties: false verbietet Felder die nicht in properties stehen. Default ist true (alles erlaubt). In APIs typisch false setzen, damit ein Tippfehler im Client (z.B. emial statt email) sofort einen Validation-Error wirft.

Verwandt: Properties

Die schnellste JSON-Schema-Library für JavaScript/Node.js.

Ajv (Another JSON Schema Validator) kompiliert Schemas zur Laufzeit in optimierten JavaScript-Code. Unterstützt Draft 04, 06, 07, 2019-09 und 2020-12. Über 90 % aller npm-Pakete die JSON-Validation machen, nutzen Ajv unter der Haube. Performance: oft 10-30× schneller als andere Libraries.

Verwandt: JSON Schema,Validator

Schema-Komposition: Wert muss zu allen Sub-Schemas passen.

allOf nimmt ein Array von Schemas, ALLE müssen passen. Klassischer Use-Case: Schema-Erweiterung (Mixin-Pattern). Beispiel: ein User-Schema kombiniert mit einem Timestamps-Schema. Achtung: Performance-Einbußen bei vielen Sub-Schemas.

Verwandt: anyOf,oneOf

Schema-Komposition: Wert muss zu mindestens einem Sub-Schema passen.

anyOf ist die toleranteste Komposition: der Wert muss zu mindestens einem der Sub-Schemas passen. Mehrfach-Match ist erlaubt. Klassischer Use-Case: type: ["string", "number"] als alternative Schreibweise oder offene Union-Typen.

Verwandt: allOf,oneOf

Erlaubt genau einen einzigen Wert.

const ist die Single-Value-Variante von enum. Sinnvoll vor allem in oneOf-Konstrukten zur Diskriminierung von Varianten. Beispiel: { const: "user" } für ein type-Feld.

Verwandt: Enum,oneOf

Vorgeschlagener Wert wenn das Feld fehlt - informativ, nicht enforced.

default macht keine Validation. Es ist Metadata für Generatoren und UI-Tooling. Manche Validator-Implementierungen (z.B. Ajv mit useDefaults: true) füllen fehlende Felder automatisch - das ist eine Erweiterung, nicht Standard.

Verwandt: Required

Erlaubt nur Werte aus einer expliziten Liste.

enum ist ein Array möglicher Werte. Funktioniert mit allen Typen, nicht nur Strings. Beispiel: { enum: ["draft", "published", "archived"] }. Für riesige Listen besser pattern oder $ref auf ein externes Schema nutzen.

Verwandt: Const,Type

Semantischer String-Check (date-time, email, uri, uuid, ...).

format prüft Strings auf semantische Korrektheit. In Ajv erst aktiv mit ajv-formats Package. Default-Behavior: format wird angezeigt im Schema, hat aber keine Wirkung. Klassische Formate: date-time (RFC 3339), email (subset von RFC 5322), uri, uuid, ipv4, ipv6, hostname.

Verwandt: Pattern,Date-Time

Konditionelle Schema-Validation seit Draft 07.

if/then/else implementiert Bedingungen: wenn das if-Schema matcht, muss auch das then-Schema matchen, sonst das else-Schema. Beispiel: wenn type=premium, dann muss subscription_end gesetzt sein. Mehrere if/then/else-Blöcke per allOf kombinierbar.

Verwandt: allOf,oneOf

Backend-Validation-Library aus dem Hapi-Ökosystem.

Joi ist ein Schema-Builder ähnlich Yup, primär für Node.js-Backends gedacht. Sehr ausdrucksstarke API (Joi.object().keys({...}).min(1).max(10)). Wird oft in Express/Fastify-Middleware eingesetzt. Hat eine eigene DSL - kein direkter Export nach JSON Schema.

Verwandt: Zod,Yup

Textbasiertes Datenaustauschformat aus dem JavaScript-Umfeld, RFC 8259.

JSON (JavaScript Object Notation) ist ein offenes, textbasiertes Datenformat, das aus JavaScript-Objekt-Literalen abgeleitet wurde und 2017 als RFC 8259 standardisiert wurde. Es kennt nur sechs Datentypen: object, array, string, number, boolean, null. Keine Kommentare, keine trailing commas. Standardformat für REST-APIs und Konfigurationsdateien.

Verwandt: JSON Schema,JSON.parse

Vertragsformat das Struktur und Constraints von JSON-Dokumenten beschreibt.

JSON Schema ist selbst JSON und beschreibt, wie ein gültiges JSON-Dokument auszusehen hat: welche Felder Pflicht sind, welche Typen erlaubt sind, welche Wertebereiche gelten. Aktuelle Version: Draft 2020-12. JSON Schema ist die Sprache hinter OpenAPI 3.1 für Request/Response-Bodies.

Verwandt: Draft 2020-12,$schema,Validator

Schema-Komposition: Wert darf NICHT zum Sub-Schema passen.

not negiert ein Schema. Beispiel: { not: { type: "string" } } heißt "kein String erlaubt". Selten direkt nützlich, oft in Kombination mit allOf um Constraints auszuschließen. Anti-Pattern: doppeltes not - meist Indikator dass das Schema-Design unsauber ist.

Verwandt: allOf,anyOf

Schema-Komposition: Wert muss zu GENAU einem Sub-Schema passen.

oneOf erzwingt Exclusive-Or: passt zu genau einem Sub-Schema. Bei mehrfach-Match: Validation-Error. Klassischer Use-Case: Tagged Unions / Discriminated Unions. Performance-Tipp: discriminator-Keyword (in OpenAPI) signalisiert dem Validator wo er zuerst hinschauen soll.

Verwandt: allOf,anyOf,Const

Schema-Keyword: Regex-Constraint für String-Werte.

pattern erwartet einen ECMA-262-Regex als String. Beispiel: { type: "string", pattern: "^[A-Z]{2,3}-\\d{4}$" } für Codes wie "DE-1234". Vorsicht bei Backslash-Escaping: doppelt im JSON-String.

Verwandt: Format,Enum

Schema-Keyword zur Beschreibung der Felder eines Objekts.

properties ist ein Objekt, dessen Keys die Feldnamen sind, und dessen Values jeweils ein eigenes Sub-Schema sind. Felder die nicht in properties stehen, sind per Default erlaubt - additionalProperties: false muss explizit gesetzt werden um das zu verbieten.

Verwandt: Required,Additional Properties

Array von Feldnamen, die im Objekt vorhanden sein müssen.

required ist ein Array von Strings (NICHT ein Objekt). Stehen Felder darin, müssen sie im validierten Objekt vorhanden sein - Wert null oder leerer String zählt als "vorhanden". Typischer Anfänger-Fehler: required innerhalb von properties statt parallel dazu setzen.

Verwandt: Properties,Type

Struktur-Beschreibung eines Datenformats.

Im Kontext von JSON Schema ist ein Schema ein JSON-Dokument, das andere JSON-Dokumente beschreibt: erlaubte Typen, Pflichtfelder, Wertebereiche, Patterns. Ein Schema kann auch nur ein einzelnes Boolean-true (= alles erlaubt) oder false (= nichts erlaubt) sein.

Verwandt: JSON Schema,$schema

Das wichtigste Schema-Keyword: legt den Datentyp eines Werts fest.

type kann sein: "string", "number", "integer", "boolean", "object", "array", "null". Auch ein Array mehrerer Typen ist erlaubt (z.B. ["string", "null"] für nullable Strings). Anders als der TypeScript-Type-System: "integer" ist ein eigener Typ, nicht ein Subset von number.

Verwandt: Properties,Required

Tool oder Library die prüft ob ein JSON-Dokument einem Schema entspricht.

Ein Validator nimmt ein JSON-Dokument und ein JSON-Schema und gibt zurück: ist gültig, oder nicht (mit Fehlerliste). Klassische Implementierungen: Ajv (JS/TS), python-jsonschema (Python), opis/json-schema (PHP), justify (Java). Die meisten kompilieren das Schema in eine schnelle Validierungs-Funktion.

Verwandt: Ajv,Schema

JavaScript-Validation-Library mit Schema-Builder-API, in Formularen verbreitet.

Yup nutzt ebenfalls einen Schema-Builder (yup.object().shape({...})), ist aber weniger TypeScript-zentriert als Zod. Klassische Verwendung: Formik-Formulare. Hat eine eingebaute when()-Funktion für konditionelle Validation. Performance liegt unter Ajv, ist aber für UI-Formulare ausreichend.

Verwandt: Zod,Joi

TypeScript-First-Validation mit Builder-Pattern und Type-Inference.

Zod ist eine TypeScript-Library, in der Schemas via Code aufgebaut werden (z.B. z.object({ name: z.string() })). Daraus kann TypeScript automatisch den Typ ableiten - kein doppeltes Schreiben von Schema und Type. Beliebt in modernen Next.js/React-Stacks. Kein JSON-Schema-Output by default (nur via zod-to-json-schema).

Verwandt: Yup,Joi