axross/skills

Zod Schema

Nutzen Sie diese Fähigkeit immer dann, wenn eine Änderung Zod betrifft – wenn ein Schema geschrieben, ein Parse platziert, eine Nutzlast dekodiert oder ein Fehler angezeigt wird. Sie besitzt die Schemaschicht: die Form, den Parse-Aufruf, den Typ, den diese Form ergibt, den Fehler, den sie produziert, und den Codec, der Daten zwischen einem Drahtformat und einem Domänenmodell überträgt.

Sie besitzt nicht vier benachbarte Fragen, die jeweils von einer eigenen Fähigkeit beantwortet werden:

• Ob eine Eingabe überhaupt nicht vertrauenswürdig ist und daher überprüft werden muss – ein Urteil einer Anwendungssicherheits-Fähigkeit. Diese Fähigkeit geht davon aus, dass dieses Urteil gefällt wurde, und beschreibt, wie Zod es umsetzt.
• Dass es einen Hook für den Parse gibt – einen Route-Handler, eine Serverfunktion, eine Formularaktion – eine Tatsache einer Framework-Fähigkeit.
• Wann eine abgerufene Nutzlast erneut abgerufen, zwischengespeichert oder ungültig gemacht wird – eine Angelegenheit der Serverzustands-Fähigkeit. Diese Fähigkeit platziert nur einen Parse innerhalb der Abfragefunktion, die sie besitzt.
• Wie eine Komponente das geparste Ergebnis erhält, rendert und dagegen testet – eine Angelegenheit der Komponentenentwicklungs-Fähigkeit.

Wo eine Regel hier ein Gegenstück in einer dieser Fähigkeiten hat, nennt diese Fähigkeit den Zod-Mechanismus und den anderen als Eigentümer.

Versionsdisziplin. Diese Fähigkeit wurde gegen Zod 4 entwickelt. Zod 3 ist als unterstützte Version nicht vorgesehen: kein Migrationspfad, keine zod/v3-Anleitung und keine Regel in ihrer Zod-3-Form. Der einzige Ort, an dem Zod 3 vorkommt, ist als Erkennungssignal – eine Liste veralteter Idiome, damit veralteter Code erkannt und durch die aktuelle Form ersetzt werden kann. Dies ist eine Zod-4-Regel über eine Zod-4-Codebasis, keine Abdeckung von Zod 3. Die Grenze ist hier wichtiger als üblich, da Zod-3-Antworten in Tutorials, Forenbeiträgen und im Modellabruf immer noch Vorrang vor Zod-4-Antworten haben – und die meisten Zod-3-Idiome kompilieren immer noch gegen eine Zod-4-Installation, daher ist „es läuft“ kein Beweis dafür, dass eine Regel aktuell ist. Zod 4 bewegt sich auch innerhalb seiner Hauptversion: z.xor, z.invertCodec und der .brand-Richtungsparameter kamen alle nach 4.0. Jede versionssensitive Aussage hier nennt, wogegen sie verifiziert wurde, und wo eine Oberfläche bekanntermaßen variiert, ist die Regel ein Nachschlagen – konsultieren Sie die Dokumentation der installierten Version unter https://zod.dev/ – anstatt eines eingefrorenen API-Namens. Behandeln Sie eine nicht versionierte Behauptung über eine Zod-API, in dieser Fähigkeit oder anderswo, als verdächtig.

Verifiziert gegen [email protected], veröffentlicht am 2026-05-04 – https://zod.dev/ – mit TypeScript 5.5+ und strict: true als genannten Voraussetzungen. Jede Referenzdatei trägt ihre eigene 'Verifiziert gegen'-Zeile mit der Upstream-Seite, gegen die ihre Regeln geprüft wurden.

Nicht im Fokus. Zod 3 in jeder Form. Die 4.5.0-canary-Linie, gegen die keine Regel hier abgeleitet wurde. Andere Validierungsbibliotheken, außer wo eine Grenze mit einer geteilt wird – Standard-Schema-Interoperabilität wird abgedeckt, Valibots oder ArkTypes eigene APIs nicht. Codegenerierungstools, die Zod-Schemata ausgeben, werden genannt, wo sie ändern, was Sie trotzdem von Hand schreiben müssen, aber ihre eigene Konfiguration gehört ihnen.

Die Schlüsselwörter „MUSS“, „DARF NICHT“, „ERFORDERLICH“, „SOLL“, „SOLL NICHT“, „EMPFOHLEN“, „KANN“ und „OPTIONAL“ in diesem Dokument sind so zu interpretieren, wie in RFC 2119 beschrieben.

Die Validierungsgrenze

Siehe validation-boundary.md für:

• den einen Parse an der Grenze zu platzieren, an der Daten eintreten, und niemals inward davon erneut zu parsen
• unknown oberhalb des Parses und z.infer<typeof Schema> unterhalb, niemals eine handgeschriebene Schnittstelle
• welche Fragen zu einer Anwendungssicherheits-, Framework-, Serverzustands- oder Komponenten-Fähigkeit gehören
• die Fälle, in denen ein Schema kostet, ohne zu kaufen – interne Daten, ein bereits geparster Wert, eine Schleife pro Element
• Zod neben einem zweiten Validator auszuführen und zwischen ihnen an einer Stelle zu konvertieren

Version und Pakete

Siehe version-and-packages.md für:

• zod.dev (Zod 4) von v3.zod.dev (Zod 3) zu unterscheiden, bevor Sie einer Seite vertrauen
• die Wahl zwischen zod, zod/mini, zod/locales und den zod/v4/*-Permalinks
• das vorausgesetzte TypeScript 5.5+ und strict: true, ohne das die abgeleitete Optionalität unsicher ist
• die Nebenversionsuntergrenzen für z.xor, z.invertCodec, .safeExtend, z.property und die .brand-Richtung
• die Zod-3-Idiome, die immer noch gegen Zod 4 kompilieren, als Signal für Veralterung

Schema-Module

Siehe schema-modules.md für:

• die const X / type X- und zX-Namenskonventionen und die Auswahl einer pro Repository
• gemeinsame EntityId-, Timestamp- und NonEmptyString-Primitive als Vokabular, aus dem andere Schemata zusammengesetzt werden
• .brand<"Name">(), seine "out"/"in"/"inout"-Richtung und die Fixtures, die es durch einen Parse zwingt
• Ableitung mit .shape, .extend, .safeExtend, .pick, .omit und .merge()'s 4.4-Wurf bei Verfeinerungen
• jedes Schema in den Modulbereich zu heben, anstatt es pro Anfrage oder Render neu zu erstellen

Primitive und Formate

Siehe primitives-and-formats.md für:

• die z.email(), z.url(), z.uuid() und z.iso.datetime() auf oberster Ebene, die die z.string().x()-Methoden ersetzt haben
• die Wahl von striktem z.uuid() gegenüber permissivem z.guid() und z.httpUrl() gegenüber z.url() für eine abgerufene URL
• z.stringFormat() für ein projekteigenes Format und z.templateLiteral() für einen Template-Literal-Typ
• z.int()'s safe-integer-Bereich, die Ablehnung von Infinity und die fest breiten z.int32() und z.float64()
• z.enum() gegenüber dem veralteten z.nativeEnum(), mit .exclude() und .extract()

Objekte und Sammlungen

Siehe objects-and-collections.md für:

• z.object(), das nicht modellierte Schlüssel entfernt, und z.strictObject(), z.looseObject() und .catchall(), die das ändern
• Selbstreferenz durch einen Getter und die Rückgabetyp-Annotation, die ein Zirkularitätsfehler benötigt
• z.record()'s zwei erforderliche Argumente, erschöpfende Enum-Schlüssel und z.partialRecord()
• z.tuple(), wo .nonempty() keinen Tuple-Typ mehr ergibt, plus z.file() und z.json()
• ein Array-Schema einmal zu parsen anstatt ein Item-Schema pro Element

Unions

Siehe unions.md für:

• z.discriminatedUnion() für Verengung, Fehlerqualität und Parsing-Geschwindigkeit gegenüber einem einfachen z.union()
• den literal-Diskriminator, den jeder Zweig festlegen muss, und die verschachtelten Unions und Pipes, die Zod 4 innerhalb einer erlaubt
• z.xor() für den Fall, dass ein Wert, der zwei Zweigen entspricht, ein Defekt ist
• z.intersection(), das einen einfachen Error anstatt eines ZodError auf ein nicht zusammenführbares Ergebnis wirft
• die Union von optionalen Feldformen, die ein Objekt hätten sein sollen

Optionalität und Standardwerte

Siehe optionality-and-defaults.md für:

• die Wahl von .optional(), .nullable() oder .nullish() basierend darauf, was der Produzent tatsächlich ausgibt
• .default(), das den Ausgabetyp kurzschließt, gegenüber .prefault(), das den Eingabetyp parst
• .catch(), das einen Parse-Fehler in einen Fallback verwandelt, und wann das einen abweichenden Produzenten verbirgt
• .nullish().transform((v) => v ?? null), um einen gemischten null-und-undefined-Produzenten zu reduzieren
• was exactOptionalPropertyTypes mit dem abgeleiteten Typ einer optionalen Eigenschaft macht

Verfeinerungen

Siehe refinements.md für:

• .refine(), .superRefine() und .check() und die Regel, dass keine von ihnen werfen darf
• ctx.addIssue(), z.NEVER und der path, der einen Fehler auf einem bestimmten Feld landen lässt
• abort, um eine Kette zu stoppen, und 4.4's when, um eine Prüfung zu überspringen, deren Eingaben bereits ungültig sind
• eine asynchrone Verfeinerung, die .parseAsync() auf jedem existierenden Aufrufer des zusammengesetzten Schemas erzwingt
• eine Berechtigungs-, Kontingent- oder Eindeutigkeitsregel, die in die Domäne und nicht in das Schema gehört

Transformationen und Pipes

Siehe transforms-and-pipes.md für:

• .transform() nach der Validierung, z.preprocess() davor und .pipe() zwischen zwei Schemata
• .overwrite(), wo der Wert sich ändert, aber der Typ und seine Introspektierbarkeit nicht
• z.input versus z.output/z.infer und die Form- und Fixture-Fehler, die durch Verwechslung entstehen
• ctx.issues.push oder 4.4's ctx.addIssue mit z.NEVER, um innerhalb einer Transformation zu scheitern
• wo die Umformung der Produzentendaten endet und eine Domänenentscheidung beginnt

Codecs

Siehe codecs.md für:

• z.codec(input, output, { decode, encode }) für eine Grenze, die .transform() nicht umkehren kann
• .decode() und .encode() mit ihren safe*- und *Async-Formen, plus z.invertCodec()
• die dokumentierten isoDatetimeToDate-, json-, stringToURL- und base64ToBytes-Vorlagen – kopiert, nicht importiert
• Standardwerte und .catch(), die nur beim Decodieren angewendet werden, und ein .transform(), das beim Encodieren einen nicht-ZodError wirft
• der totale Codec, der nicht fehlschlagen kann, und die Formgarantie, die er daher nicht gibt

Coercion und Konfiguration

Siehe coercion-and-config.md für:

• z.coerce.number().parse(""), das 0 zurückgibt, und z.coerce.boolean().parse("false"), das true zurückgibt
• z.stringbool() als das Konstrukt, das einen Wert ablehnt, der weder in der Wahrheits- noch in der Falschheitsmenge ist
• Abfragezeichenfolgen, Formulardaten und Umgebungsvariablen als die drei Quellen mit Zeichenfolgewert
• einmaliges Parsen der Konfiguration beim Start und Beenden, anstatt später undefined zu liefern
• geheime Konfiguration aus Protokollen und aus einem Client-Bundle herauszuhalten

Parsen

Siehe parsing.md für:

• .parse(), wenn ein Fehler ein Defekt ist, .safeParse(), wenn er ein Ergebnis ist, auf das verzweigt werden soll
• .parseAsync(), das obligatorisch anstatt optional ist, sobald eine Prüfung im Schema asynchron ist
• die tiefe Klon, die ein Parse zurückgibt, und die Referenzidentität, die er daher bricht
• die Zuordnung von ZodError zu einem Domänenfehler, damit Zod aus den Domänensignaturen herausbleibt
• Protokollierung der Grenze und der Issue-Pfade, niemals der Eingabe, die fehlgeschlagen ist

Fehler

Siehe errors.md für:

• error.issues mit seinem code und path und die entfernten .errors- und .formErrors-Aliase
• z.treeifyError(), z.flattenError() und z.prettifyError(), ausgewählt vom Verbraucher
• den einheitlichen error-Parameter, der message, invalid_type_error und errorMap ersetzt hat
• die Rangfolge – Schema, pro Parse, z.config({ customError }), Gebietsschema – die in Zod 4 umgekehrt wurde
• reportInput, das nicht vertrauenswürdige Eingaben in einen Fehler steckt, der zu einem Tracker oder einem Client gelangt

Metadaten und JSON Schema

Siehe metadata-and-json-schema.md für:

• .meta(), z.registry(), z.globalRegistry und das Erweitern von GlobalMeta durch Deklarationszusammenführung
• Metadatenbindung an eine Schema-Instanz, sodass .optional() oder .extend() sie verwaist
• z.toJSONSchema()'s target-, io-, unrepresentable-, cycles-, reused- und uri-Optionen
• io: "input", das ein anderes Dokument erzeugt als die Standard-Ausgabeansicht
• die date-, map-, set-, transform- und bigint-Typen ohne JSON-Schema-Darstellung

Modellstrukturierte Ausgabe

Siehe model-structured-output.md für:

• ein Schema als generateObject- oder Tool-Vertrag und satisfies z.ZodRawShape, wo eine rohe Form gewünscht wird
• .describe()-Text, der das Modell als Anweisung und nicht als Dokumentation erreicht
• .nullable(), das den strikten Modus eines Anbieters überlebt, wo .optional() und .nullish() abgelehnt werden
• die Wiederverwendung von .shape.field, damit die Modellausgabe nicht vom Domänentyp abweichen kann, den sie speist
• erneutes Auffordern aus einem ZodError unter einer begrenzten Wiederholung, anstatt ungültige Ausgabe zu patchen

Formulare

Siehe forms.md für:

• einen Zod-spezifischen Resolver für Zods eigene Issue-Details oder einen Standard-Schema-Resolver für Bibliotheksunabhängigkeit
• z.input für die Formularwerte und Standardwerte, z.output für den Submit-Handler
• path auf einer feldübergreifenden Verfeinerung als einzigen Weg, wie ein Fehler das richtige Eingabefeld erreicht
• den leeren String, den ein leeres numerisches Feld sendet, und den fehlenden Schlüssel, den eine nicht aktivierte Checkbox sendet
• das serverseitige erneute Parsen, das ein clientseitiges Schema niemals ersetzt

Datenspeicher-Grenzen

Siehe data-store-boundaries.md für:

• die gespeicherte Form und das Domänenmodell als zwei Schemata mit einer Transformation dazwischen
• Lese- und Schreibhälften, die als ein Paar geschrieben werden, damit ein umbenanntes Feld nicht zwischen ihnen abweichen kann
• .partial() für einen Patch und .omit().extend() für eine Create-Eingabe, die Speicher-Sentinels trägt
• z.instanceof() für die eigenen Typen eines Treibers und z.property(), um eines ihrer Felder einzuschränken
• eine Nutzlast, die je nach Abfragetiefe, Entwurfsstatus oder Gebietsschema variiert – und das Schema mit allen optionalen Feldern, das nicht die Antwort ist

Leistung und Speicherverbrauch

Siehe performance-and-footprint.md für:

• die veröffentlichten ~14x-, ~7x- und ~6,5x-Parse-Gewinne und den ~25.000-auf-~175-Typinstanziierungsabfall
• zod/mini's funktionale API und 1,88 kB Kern und warum ein Server es nicht übernehmen sollte
• Schema-Konstruktion, die aus einem heißen Pfad herausgehoben wurde, und eine Sammlung, die einmal anstatt pro Element geparst wird
• .check() gegenüber .refine() und eine diskriminierte Union gegenüber einer linearen, auf einem gemessenen Pfad
• z.looseObject(), das den Key-Stripping-Durchlauf überspringt, und den Schutz, den das aufgibt

Sicherheitshaltung

Siehe security-posture.md für:

• z.object()'s Stripping als Massenzuweisungsschutz und was z.looseObject() wieder zulässt
• ein bestandener Parse, der weder HTML-Escaping, SQL-Parametrisierung noch eine sichere Abrufgarantie ist
• .max(), das vor einem .regex() oder einer teuren Verfeinerung platziert wird, um die vom Angreifer kontrollierte Arbeit zu begrenzen
• unbegrenzte Arrays, unbegrenzte Rekursionstiefe und zyklische Eingabe, die für immer schleift
• ein Allowlisting-Antwortschema, ohne das ein privates Feld mit der Nutzlast geht

Testen von Schemata

Siehe testing-schemas.md für:

• warum das Behaupten, dass z.email() "nope" ablehnt, Zod anstatt des Schemas testet
• z.input<typeof Schema> als den Fixture-Typ, erstellt aus einer beobachteten Nutzlast

...