JSON-Schema-format: die wichtigsten Built-in-Formate

Was format macht (und was nicht)

format prüft Strings auf semantische Korrektheit. Beispiel: ein String der als "email" markiert ist, soll auch das Format einer E-Mail-Adresse haben. WICHTIG: format ist im Standard optional - Ajv ignoriert format ohne installiertes Plugin.

format aktivieren

import Ajv from 'ajv';
import addFormats from 'ajv-formats';

const ajv = new Ajv();
addFormats(ajv);  // Ohne diesen Aufruf wird format ignoriert!

Die wichtigsten Built-in-Formate

Format	Was geprüft wird	Beispiel-Pattern
date-time	RFC 3339 Date-Time	"2026-05-14T12:30:00Z"
date	RFC 3339 Date	"2026-05-14"
time	RFC 3339 Time	"12:30:00"
email	Vereinfachter RFC 5322	"max@example.com"
uri	RFC 3986 URI	"https://example.com/path"
uri-reference	URI oder relative Reference	"/path/sub"
uuid	RFC 4122 UUID	"550e8400-e29b-41d4-a716-446655440000"
ipv4	IPv4-Adresse	"192.168.1.1"
ipv6	IPv6-Adresse	"2001:db8::1"
hostname	RFC 1123 Hostname	"server.example.com"
regex	ECMA-262-Regex	"^[a-z]+$"

Warum email tricky ist

Die volle RFC-5322-konforme E-Mail-Regex ist über 6.000 Zeichen lang und erlaubt skurrile Adressen wie "max@[127.0.0.1]" oder "a@b". Ajv nutzt einen vereinfachten Check, der die meisten echten E-Mails akzeptiert aber Pathological-Cases abweist.

Für strenge Anwendungsfälle: format: email + zusätzlich eigene Validation. Oder besser: pragmatisch den Mail-Server entscheiden lassen (Bounce-Handling).

date-time im Detail

RFC 3339 ist ein Subset von ISO 8601:

• Muss vollständig sein: Datum + Uhrzeit + Zeitzone
• Zeitzone als "Z" für UTC oder "+02:00"
• Mikrosekunden optional: "2026-05-14T12:30:00.123Z"

NICHT akzeptiert: "2026-05-14 12:30:00" (Leerzeichen statt T), "2026-05-14T12:30:00" (keine Timezone), "14.05.2026" (deutsches Format).

Eigene Formate definieren

ajv.addFormat('iban', /^[A-Z]{2}[0-9]{2}[A-Z0-9]{4,30}$/);

const schema = {
  type: 'object',
  properties: {
    iban: { type: 'string', format: 'iban' }
  }
};

So lassen sich domänenspezifische Constraints (IBAN, USt-IdNr, ISBN) als Format einbauen - sauberer als jedes Mal pattern manuell zu schreiben.

Wann format, wann pattern?

Situation	Empfehlung
Standard-Format (email, date-time, ...)	format
Domain-spezifisch ohne Standard (IBAN, ISBN, User-ID-Format)	pattern oder eigenes format
Free-Form-Text mit grobem Constraint	pattern
Cross-Language-Schema	format (Standard-Compliance)

format-Validation-Modi

Ajv kennt drei Modi:

• "fast" (default): performant, akzeptiert mehr Edge-Cases
• "full": streng, langsamer (~10× langsamer für email)
• off: format wird ignoriert

addFormats(ajv, { mode: 'full', formats: ['email', 'date-time'] });