Standard Schema – Gemeinsame Schnittstelle für TypeScript-Validierung

• Eine Spezifikation, die so entworfen wurde, dass JavaScript-/TypeScript-basierte Schema-Bibliotheken eine gemeinsame Schnittstelle implementieren
• Ziel ist es, von Nutzern definierte Typvalidierungslogik bibliotheksübergreifend wiederverwendbar zu machen, sodass Tools ohne separate Adapter miteinander kompatibel sind
• Gemeinsam entworfen von den Machern wichtiger Bibliotheken wie Zod, Valibot und ArkType

Wichtige Schnittstelle (StandardSchemaV1)

• Die gesamte Spezifikation wird über die Objekteigenschaft ~standard implementiert
• Innerhalb von ~standard gibt es erforderliche Properties wie version, vendor, validate und types
• Die Funktion validate gibt bei Erfolg value und bei Fehlschlag ein Array issues zurück
• Über die Property types lassen sich in TypeScript die Eingabe- (input) und Ausgabe- (output) Typen des Schemas ableiten
• Alle Updates bleiben kompatibel, solange es sich nicht um eine Major-Version handelt

Designziele

• Unterstützung für Runtime-Validierung: Fehlerinformationen werden standardisiert im Standardformat übergeben
• Unterstützung für statische Typinferenz: Von TypeScript-basierten Bibliotheken abgeleitete Typinformationen werden explizit offengelegt
• Kompaktheit: Die Implementierung kann mit nur wenigen Zeilen zu bestehenden Bibliotheksfunktionen hinzugefügt werden
• Vermeidung von API-Konflikten: Alles liegt ausschließlich im Namensraum ~standard, um Kollisionen mit bestehenden APIs zu vermeiden
• Erhalt der Developer Experience: Durch den Beginn mit Tilde (~) erhält ~standard in der Autovervollständigung eine niedrigere Priorität

Welche Bibliotheken implementieren es?

• Standard Schema wird bereits von Zod, Valibot, ArkType, Arri Schema, TypeMap und weiteren unterstützt
• Auch tRPC, TanStack Form, TanStack Router und Hono Middleware akzeptieren Nutzerschemata auf Basis von Standard Schema

So implementiert man die Spezifikation in der eigenen Bibliothek

• Das Interface StandardSchemaV1 in die Bibliothek kopieren und die Property ~standard hinzufügen
• Die Funktion validate mit der bestehenden Validierungsfunktion verbinden, sodass bei Erfolg { value } und bei Fehlschlag { issues } zurückgegeben wird
• Bei Bedarf ist auch asynchrone Validierung möglich, empfohlen wird jedoch synchrone Validierung

So nimmt man benutzerdefinierte Schemata über Standard Schema entgegen

• Wer es ohne Schema-Bibliothek direkt nutzen möchte, installiert @standard-schema/spec oder kopiert das Interface zur Verwendung
• Wie bei der Beispielfunktion standardValidate kann bei jedem Schema mit Standard-Schnittstelle die Validierung bibliotheksunabhängig auf dieselbe Weise erfolgen
• Wenn nur synchrone Validierung erlaubt sein soll, genügt es zu prüfen, ob der Rückgabewert von validate ein Promise ist, und dann eine Ausnahme zu behandeln

FAQ

• Muss die Abhängigkeit @standard-schema/spec hinzugefügt werden?: Sie muss nicht zwingend als Abhängigkeit hinzugefügt werden; Kopieren und direkte Verwendung sind möglich
• Kann nicht als dev dependency hinzugefügt werden: Da sie Teil der öffentlichen API einer Bibliothek wird, muss sie auch in der tatsächlichen Laufzeitumgebung verfügbar sein
• Warum wird vor ~standard eine Tilde (~) verwendet?: Damit es in der Autovervollständigung hinter anderen Properties erscheint
• Warum wird statt Symbol ein String-Key verwendet?: Weil Symbol-Keys in TypeScript Probleme bei Sortierung in der Autovervollständigung und Typinferenz verursachen