/** @deprecated This parameter is deprecated. Use `error` instead. */ message?: string | undefined;

Replace `message` with `error`. (The `message` parameter is still supported but deprecated.)

The code shows `message` is marked `@deprecated` in favor of `error`, and the docs mention this replacement once in the 'Simplified error customization' section. However, the docs do not provide a comprehensive migration guide or warning that developers using the old API should update their code. The deprecation warning in the code is more prominent than in the documentation.

Add a dedicated migration section or warning in the error customization documentation explaining that `message` is deprecated, showing side-by-side examples of old vs. new syntax, and recommending developers update their code before the parameter is removed in Zod 5.

export type Params< T extends schemas.$ZodType | checks.$ZodCheck, IssueTypes extends errors.$ZodIssueBase, OmitKeys extends keyof T["_zod"]["def"] = never, > = util.Flatten< ... >;

(not documented)

The code exports several advanced type parameter utilities like `Params`, `TypeParams`, `CheckParams`, `StringFormatParams`, and `CheckTypeParams` used throughout the core/api.ts module. These are part of the public API surface but are not documented in the provided documentation. Developers attempting to use or extend Zod's core may be confused about how to use these types.

Add documentation explaining these type parameter utilities in the 'Zod Core' or API reference section, clarifying their purpose and when extension developers would need to use them.

export function _stringFormat<Format extends string>(Class: typeof schemas.$ZodCustomStringFormat, format: Format, fnOrRegex: ((arg: string) => util.MaybeAsync<unknown>) | RegExp, _params: string | $ZodStringFormatParams = {}): schemas.$ZodCustomStringFormat<Format>

(not documented)

The code exports `_stringFormat` function for creating custom string formats, but the documentation does not mention how developers can create their own custom string format validators beyond the built-in ones (email, uuid, etc.). The release notes mention custom email regex, but don't explain how to define entirely new string formats.

Add a section in the API documentation explaining how to create custom string formats using the exported functions, with clear examples.

export function _check<O = unknown>(fn: schemas.CheckFn<O>, params?: string | $ZodCustomParams): checks.$ZodCheck<O>

(not documented)

The code exports a `_check` function for creating custom checks, which appears to be related to or similar to `.refine()`, but this function is not documented anywhere. The purpose and use case distinction between `_check` and other refinement APIs is unclear.

Document the `_check` function in the 'Custom checks' or 'Refinements' section, explaining how it differs from `.refine()`, `.superRefine()`, etc., and when developers should use it.

export function _string<T extends schemas.$ZodString>(Class: util.SchemaClass<T>, params?: string | $ZodStringParams): T
export function _coercedString<T extends schemas.$ZodString>(Class: util.SchemaClass<T>, params?: string | $ZodStringParams): T

(not documented)

The code exports internal functions like `_string`, `_coercedString`, `_number`, `_coercedNumber`, etc. that are used to create schema instances. These functions are not mentioned in the documentation, though they may be used internally or by library authors extending Zod. Their naming convention (underscore prefix) suggests they may be internal, but they are explicitly exported from the public API.

Clarify in the 'For library authors' documentation whether these functions are intended for internal use only or if they should be used by extension developers, and document their purpose if they are part of the public extension API.

export function describe<T>(description: string): checks.$ZodCheck<T>
export function meta<T>(metadata: registries.GlobalMeta): checks.$ZodCheck<T>

For compatibility with Zod 3, `.describe()` is still available, but `.meta()` is preferred.

The code exports standalone `describe` and `meta` functions (which return checks), but the documentation only mentions `.describe()` and `.meta()` as methods on schemas. The functional API variants are not explicitly documented, though they are part of the public API.

Clarify in the Zod Mini or API documentation that `describe()` and `meta()` are available as standalone functions and show functional API examples alongside the method examples.

export function _overwrite<T>(tx: (input: T) => T): checks.$ZodCheckOverwrite<T>
export function _normalize(form?: "NFC" | "NFD" | "NFKC" | "NFKD" | (string & {})): checks.$ZodCheckOverwrite<string>
export function _trim(): checks.$ZodCheckOverwrite<string>
export function _toLowerCase(): checks.$ZodCheckOverwrite<string>
export function _toUpperCase(): checks.$ZodCheckOverwrite<string>
export function _slugify(): checks.$ZodCheckOverwrite<string>

z.trim();
z.toLowerCase();
z.toUpperCase();

While the docs mention `.trim()`, `.toLowerCase()`, and `.toUpperCase()` as methods in the Zod Mini section and show them as part of the functional API, the code exports internal functions `_trim`, `_toLowerCase`, `_toUpperCase`, `_normalize`, `_overwrite`, and `_slugify`. The underscore-prefixed functions are the actual implementation, but the docs don't explain how or where `_slugify` and `_normalize` fit into the public API or if they are accessible to users.

Document `_normalize` and `_slugify` in the Zod Mini API section or clarify if these are for internal use only. If they are public, provide examples of how to use them in Zod Mini.

// FILE: packages/zod/src/v3/index.ts
export * from "./external.js"
export { z }
export default z

Zod is tested against _TypeScript v5.5_ and later.

The code exports Zod v3 as a separate entry point, and the docs mention migration from v3 to v4, but there is no detailed documentation on what changed in the v3 API compared to v4, making it hard for developers still on v3 to understand migration paths.

Link the migration guide more prominently from the intro page and ensure it covers the major v3→v4 breaking changes in detail.

export const TimePrecision

(not documented)

The code exports `TimePrecision` as a const (line 501) but its type and purpose are not shown in the code snippet and are not documented. It is referenced in relation to ISO datetime formats but its usage is unclear.

Add documentation or a note in the ISO datetime formats section explaining what `TimePrecision` is and how to use it (e.g., type declaration, examples).