5 mismatches found
01Documented z.uuidv8() has no corresponding implementation
packages/zod/src/v4/core/api.ts
highIn the code
export function _uuidv4<...>(...): T // L147
export function _uuidv6<...>(...): T // L165
export function _uuidv7<...>(...): T // L183
In the docs
z.uuidv4();
z.uuidv7();
z.uuidv8();
The release notes list `z.uuidv8()` among the top-level string formats, but the core api only defines `_uuidv4`, `_uuidv6`, and `_uuidv7` factories — there is no `_uuidv8`. A developer calling `z.uuidv8()` per the docs would likely hit a runtime/type error.
Suggested fix
Remove `z.uuidv8()` from the documented top-level string formats (or add the missing implementation). The supported UUID variants are uuidv4, uuidv6, and uuidv7.
02z.xor() schema factory is undocumented
packages/zod/src/v4/core/api.ts
mediumIn the code
export type $ZodXorParams = TypeParams<schemas.$ZodXor, "options">; // L1195
export function _xor<const T extends readonly schemas.$ZodObject[]>(Class: util.SchemaClass<schemas.$ZodXor>, options: T, params?: string | $ZodXorParams): schemas.$ZodXor<T> // L1196
In the docs
(not documented)
The core API exposes an `_xor` factory and `$ZodXor`/`$ZodXorParams` types (the implementation behind a public `z.xor()`), but no documentation page describes this exclusive-union schema type. Users have no guidance on this API.
Suggested fix
Document `z.xor()` (exclusive union) alongside `z.union()` and `z.discriminatedUnion()`, including its options/params signature.
03z.slugify() overwrite helper is undocumented
packages/zod/src/v4/core/api.ts
lowIn the code
export function _slugify(): checks.$ZodCheckOverwrite<string> // L1153
In the docs
// overwrites (these *do not* change the inferred type!)
z.overwrite(value => newValue);
z.normalize();
z.trim();
z.toLowerCase();
z.toUpperCase();
The code exposes a `_slugify()` overwrite factory (public `z.slugify()`), but the documented list of overwrite helpers omits it. Developers won't discover this transform from the docs.
Suggested fix
Add `z.slugify()` to the documented list of overwrite helpers in the Zod Mini / refinements sections.
04superRefine `when` option not documented
packages/zod/src/v4/core/api.ts
lowIn the code
export interface $ZodSuperRefineParams { when?: ((payload: schemas.ParsePayload) => boolean) | undefined; } // L1653
export function _superRefine<T>(fn: (arg: T, payload: $RefinementCtx<T>) => void | Promise<void>, params?: $ZodSuperRefineParams): checks.$ZodCheck<T> // L1659
In the docs
(not documented)
`_superRefine` accepts a `params` object with a `when` predicate that gates whether the refinement runs, but the documentation does not mention this option for super-refinements/checks.
Suggested fix
Document the `{ when }` parameter for `.superRefine()`/`.check()` super-refinements, explaining it only runs the refinement when the predicate returns true.
05Codecs docs reference z.hex() and z.httpUrl() not present in core api
packages/zod/src/v4/core/api.ts
lowIn the code
// no _hex / _httpUrl factory present in api.ts (only _url, _base64, _base64url, etc.)
In the docs
const hexToBytes = z.codec(z.hex(), z.instanceof(Uint8Array), {...});
const stringToHttpURL = z.codec(z.httpUrl(), z.instanceof(URL), {...});
The codecs page uses `z.hex()` and `z.httpUrl()`, but the core api surface defines no corresponding string-format factories (`_hex`, `_httpUrl`). These may live elsewhere, but as shown the helpers have no factory here, so the snippets could mislead if these formats don't exist.
Suggested fix
Verify `z.hex()` and `z.httpUrl()` are exported; if not, update the codec examples to use existing formats (e.g. `z.string().regex(...)`, `z.url()`).