Using native storage for examples

CHANGELOG.md

@@ -13,9 +13,8 @@
       - the temporary nature of this transition;
       - the advantages of Zod 4 that provide opportunities to simplifications and corrections of known issues.
   - `IOSchema` type had to be simplified down to a schema resulting to an `object`, but not an `array`;
-  - Despite supporting examples by the new Zod method `.meta()`, users should still use `.example()` to set them;
   - Refer to [Migration guide on Zod 4](https://v4.zod.dev/v4/changelog) for adjusting your schemas;
-- Generating Documentation is partially delegated to Zod 4 `z.toJSONSchema()`:
+- Generating Documentation is mostly delegated to Zod 4 `z.toJSONSchema()`:
   - The basic depiction of each schema is now natively performed by Zod 4;
   - Express Zod API implements some overrides and improvements to fit it into OpenAPI 3.1 that extends JSON Schema;
   - The `numericRange` option removed from `Documentation` class constructor argument;
@@ -26,6 +25,7 @@
   - Use `.or(z.undefined())` to add `undefined` to the type of the object property;
   - Reasoning: https://x.com/colinhacks/status/1919292504861491252;
   - `z.any()` and `z.unknown()` are not optional, details: https://v4.zod.dev/v4/changelog#changes-zunknown-optionality.
+- The `getExamples()` public helper removed — use `.meta()?.examples` instead;
 - Consider the automated migration using the built-in ESLint rule.
 
 ```js

example/endpoints/update-user.ts

@@ -1,6 +1,6 @@
 import createHttpError from "http-errors";
 import assert from "node:assert/strict";
-import { z } from "zod/v4";
+import { $brand, z } from "zod/v4";
 import { ez } from "express-zod-api";
 import { keyAndTokenAuthenticatedEndpointsFactory } from "../factories";
 
@@ -12,15 +12,17 @@ export const updateUserEndpoint =
       // id is the route path param of /v1/user/:id
       id: z
         .string()
+        .example("12") // before transformation
         .transform((value) => parseInt(value, 10))
-        .refine((value) => value >= 0, "should be greater than or equal to 0")
-        .example("12"),
+        .refine((value) => value >= 0, "should be greater than or equal to 0"),
       name: z.string().nonempty().example("John Doe"),
-      birthday: ez.dateIn().example("1963-04-21"),
+      birthday: ez.dateIn().example(new Date("1963-04-21") as Date & $brand),
     }),
     output: z.object({
       name: z.string().example("John Doe"),
-      createdAt: ez.dateOut().example(new Date("2021-12-31")),
+      createdAt: ez
+        .dateOut()
+        .example("2021-12-31T00:00:00.000Z" as string & $brand),
     }),
     handler: async ({
       input: { id, name },

example/example.documentation.yaml

@@ -111,9 +111,9 @@ paths:
           description: PATCH /v1/user/:id Parameter
           schema:
             type: string
-            minLength: 1
             examples:
               - "1234567890"
+            minLength: 1
           examples:
             example1:
               value: "1234567890"
@@ -136,15 +136,15 @@ paths:
               type: object
               properties:
                 key:
-                  type: string
-                  minLength: 1
                   examples:
                     - 1234-5678-90
-                name:
                   type: string
                   minLength: 1
+                name:
                   examples:
                     - John Doe
+                  type: string
+                  minLength: 1
                 birthday:
                   description: YYYY-MM-DDTHH:mm:ss.sssZ
                   type: string
@@ -153,7 +153,7 @@ paths:
                   externalDocs:
                     url: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString
                   examples:
-                    - 1963-04-21
+                    - 1963-04-21T00:00:00.000Z
               required:
                 - key
                 - name
@@ -163,7 +163,7 @@ paths:
                 value:
                   key: 1234-5678-90
                   name: John Doe
-                  birthday: 1963-04-21
+                  birthday: 1963-04-21T00:00:00.000Z
         required: true
       security:
         - APIKEY_1: []
@@ -183,9 +183,9 @@ paths:
                     type: object
                     properties:
                       name:
-                        type: string
                         examples:
                           - John Doe
+                        type: string
                       createdAt:
                         description: YYYY-MM-DDTHH:mm:ss.sssZ
                         type: string

express-zod-api/src/common-helpers.ts

@@ -5,7 +5,6 @@ import { globalRegistry, z } from "zod/v4";
 import { CommonConfig, InputSource, InputSources } from "./config-type";
 import { contentTypes } from "./content-type";
 import { OutputValidationError } from "./errors";
-import { metaSymbol } from "./metadata";
 import { AuxMethod, Method } from "./method";
 
 /** @desc this type does not allow props assignment, but it works for reading them when merged with another interface */
@@ -93,9 +92,9 @@ export const isSchema = <T extends $ZodType>(
 
 /** Takes the original unvalidated examples from the properties of ZodObject schema shape */
 export const pullExampleProps = <T extends $ZodObject>(subject: T) =>
-  Object.entries(subject._zod.def.shape).reduce<Partial<z.input<T>>[]>(
+  Object.entries(subject._zod.def.shape).reduce<Partial<z.output<T>>[]>(
     (acc, [key, schema]) => {
-      const { examples = [] } = globalRegistry.get(schema)?.[metaSymbol] || {};
+      const { examples = [] } = globalRegistry.get(schema) || {};
       return combinations(acc, examples.map(R.objOf(key)), ([left, right]) => ({
         ...left,
         ...right,
@@ -104,47 +103,6 @@ export const pullExampleProps = <T extends $ZodObject>(subject: T) =>
     [],
   );
 
-export const getExamples = <
-  T extends $ZodType,
-  V extends "original" | "parsed" | undefined,
->({
-  schema,
-  variant = "original",
-  validate = variant === "parsed",
-  pullProps = false,
-}: {
-  schema: T;
-  /**
-   * @desc examples variant: original or parsed
-   * @example "parsed" — for the case when possible schema transformations should be applied
-   * @default "original"
-   * @override validate: variant "parsed" activates validation as well
-   * */
-  variant?: V;
-  /**
-   * @desc filters out the examples that do not match the schema
-   * @default variant === "parsed"
-   * */
-  validate?: boolean;
-  /**
-   * @desc should pull examples from properties — applicable to ZodObject only
-   * @default false
-   * */
-  pullProps?: boolean;
-}): ReadonlyArray<V extends "parsed" ? z.output<T> : z.input<T>> => {
-  let examples = globalRegistry.get(schema)?.[metaSymbol]?.examples || [];
-  if (!examples.length && pullProps && isSchema<$ZodObject>(schema, "object"))
-    examples = pullExampleProps(schema);
-  if (!validate && variant === "original") return examples;
-  const result: Array<z.input<T> | z.output<T>> = [];
-  for (const example of examples) {
-    const parsedExample = z.safeParse(schema, example);
-    if (parsedExample.success)
-      result.push(variant === "parsed" ? parsedExample.data : example);
-  }
-  return result;
-};
-
 export const combinations = <T>(
   a: T[],
   b: T[],

express-zod-api/src/documentation-helpers.ts

@@ -23,11 +23,10 @@ import {
   TagObject,
 } from "openapi3-ts/oas31";
 import * as R from "ramda";
-import { z } from "zod/v4";
+import { globalRegistry, z } from "zod/v4";
 import { ResponseVariant } from "./api-response";
 import {
   FlatObject,
-  getExamples,
   getRoutePathParams,
   getTransformedType,
   isObject,
@@ -154,6 +153,7 @@ export const depictLiteral: Depicter = ({ jsonSchema }) => ({
   ...jsonSchema,
 });
 
+/** @todo might no longer be required */
 export const depictObject: Depicter = (
   { zodSchema, jsonSchema },
   { isResponse },
@@ -195,31 +195,35 @@ const ensureCompliance = ({
   return valid;
 };
 
-export const depictDateIn: Depicter = ({}, ctx) => {
+export const depictDateIn: Depicter = ({ zodSchema }, ctx) => {
   if (ctx.isResponse)
     throw new DocumentationError("Please use ez.dateOut() for output.", ctx);
-  return {
+  const jsonSchema: JSONSchema.StringSchema = {
     description: "YYYY-MM-DDTHH:mm:ss.sssZ",
     type: "string",
     format: "date-time",
     pattern: /^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d+)?)?Z?$/.source,
-    externalDocs: {
-      url: isoDateDocumentationUrl,
-    },
+    externalDocs: { url: isoDateDocumentationUrl },
   };
+  const examples = globalRegistry
+    .get(zodSchema) // zod::toJSONSchema() does not provide examples for the input size of a pipe
+    ?.examples?.filter((one) => one instanceof Date)
+    .map((one) => one.toISOString());
+  if (examples?.length) jsonSchema.examples = examples;
+  return jsonSchema;
 };
 
-export const depictDateOut: Depicter = ({}, ctx) => {
+export const depictDateOut: Depicter = ({ jsonSchema: { examples } }, ctx) => {
   if (!ctx.isResponse)
     throw new DocumentationError("Please use ez.dateIn() for input.", ctx);
-  return {
+  const jsonSchema: JSONSchema.StringSchema = {
     description: "YYYY-MM-DDTHH:mm:ss.sssZ",
     type: "string",
     format: "date-time",
-    externalDocs: {
-      url: isoDateDocumentationUrl,
-    },
+    externalDocs: { url: isoDateDocumentationUrl },
   };
+  if (examples?.length) jsonSchema.examples = examples;
+  return jsonSchema;
 };
 
 export const depictBigInt: Depicter = () => ({
@@ -282,6 +286,7 @@ export const depictPipeline: Depicter = ({ zodSchema, jsonSchema }, ctx) => {
       );
       if (targetType && ["number", "string", "boolean"].includes(targetType)) {
         return {
+          ...jsonSchema,
           type: targetType as "number" | "string" | "boolean",
         };
       }
@@ -373,7 +378,7 @@ export const depictRequestParams = ({
         schema: result,
         examples: enumerateExamples(
           isSchemaObject(depicted) && depicted.examples?.length
-            ? depicted.examples // own examples or from the flat:
+            ? depicted.examples // own examples or from the flat: // @todo check if both still needed
             : R.pluck(
                 name,
                 flat.examples?.filter(R.both(isObject, R.has(name))) || [],
@@ -403,18 +408,6 @@ const depicters: Partial<Record<FirstPartyKind | ProprietaryBrand, Depicter>> =
     [ezRawBrand]: depictRaw,
   };
 
-const onEach: Depicter = ({ zodSchema, jsonSchema }, { isResponse }) => {
-  const result = { ...jsonSchema };
-  const examples = getExamples({
-    schema: zodSchema,
-    variant: isResponse ? "parsed" : "original",
-    validate: true,
-    pullProps: true,
-  });
-  if (examples.length) result.examples = examples.slice();
-  return result;
-};
-
 /**
  * postprocessing refs: specifying "uri" function and custom registries didn't allow to customize ref name
  * @todo is there a less hacky way to do that?
@@ -462,7 +455,6 @@ const depict = (
           for (const key in zodCtx.jsonSchema) delete zodCtx.jsonSchema[key];
           Object.assign(zodCtx.jsonSchema, overrides);
         }
-        Object.assign(zodCtx.jsonSchema, onEach(zodCtx, ctx));
       },
     },
   ) as JSONSchema.ObjectSchema;
@@ -681,7 +673,7 @@ export const depictBody = ({
     examples: enumerateExamples(
       examples.length
         ? examples
-        : flattenIO(request)
+        : flattenIO(request) // @todo this branch might no longer be required
             .examples?.filter(
               (one): one is FlatObject => isObject(one) && !Array.isArray(one),
             )

express-zod-api/src/index.ts

@@ -6,7 +6,7 @@ export {
   defaultEndpointsFactory,
   arrayEndpointsFactory,
 } from "./endpoints-factory";
-export { getExamples, getMessageFromError } from "./common-helpers";
+export { getMessageFromError } from "./common-helpers";
 export { ensureHttpError } from "./result-helpers";
 export { BuiltinLogger } from "./builtin-logger";
 export { Middleware } from "./middleware";

express-zod-api/src/json-schema-helpers.ts

@@ -51,14 +51,6 @@ export const flattenIO = (
     }
     if (entry.anyOf) stack.push(...R.map(nestOptional, entry.anyOf));
     if (entry.oneOf) stack.push(...R.map(nestOptional, entry.oneOf));
-    if (!isJsonObjectSchema(entry)) continue;
-    if (entry.properties) {
-      flat.properties = (mode === "throw" ? propsMerger : R.mergeDeepRight)(
-        flat.properties,
-        entry.properties,
-      );
-      if (!isOptional && entry.required) flatRequired.push(...entry.required);
-    }
     if (entry.examples?.length) {
       if (isOptional) {
         flat.examples = R.concat(flat.examples || [], entry.examples);
@@ -70,6 +62,14 @@ export const flattenIO = (
         );
       }
     }
+    if (!isJsonObjectSchema(entry)) continue;
+    if (entry.properties) {
+      flat.properties = (mode === "throw" ? propsMerger : R.mergeDeepRight)(
+        flat.properties,
+        entry.properties,
+      );
+      if (!isOptional && entry.required) flatRequired.push(...entry.required);
+    }
     if (entry.propertyNames) {
       const keys: string[] = [];
       if (typeof entry.propertyNames.const === "string")

express-zod-api/src/metadata.ts

@@ -1,24 +1,22 @@
-import type { $ZodType } from "zod/v4/core";
-import { combinations } from "./common-helpers";
+import type { $ZodType, $ZodObject } from "zod/v4/core";
+import { combinations, isSchema, pullExampleProps } from "./common-helpers";
 import { z } from "zod/v4";
 import * as R from "ramda";
 
 export const metaSymbol = Symbol.for("express-zod-api");
 
-export interface Metadata {
-  examples: unknown[];
-}
-
 export const mixExamples = <A extends z.ZodType, B extends z.ZodType>(
   src: A,
   dest: B,
 ): B => {
-  const srcMeta = src.meta();
+  const srcExamples =
+    src.meta()?.examples ||
+    (isSchema<$ZodObject>(src, "object") ? pullExampleProps(src) : undefined);
+  if (!srcExamples?.length) return dest;
   const destMeta = dest.meta();
-  if (!srcMeta?.[metaSymbol]) return dest; // ensures srcMeta[metaSymbol]
-  const examples = combinations(
-    destMeta?.[metaSymbol]?.examples || [],
-    srcMeta[metaSymbol].examples || [],
+  const examples = combinations<z.output<A> & z.output<B>>(
+    destMeta?.examples || [],
+    srcExamples,
     ([destExample, srcExample]) =>
       typeof destExample === "object" &&
       typeof srcExample === "object" &&
@@ -27,10 +25,7 @@ export const mixExamples = <A extends z.ZodType, B extends z.ZodType>(
         ? R.mergeDeepRight(destExample, srcExample)
         : srcExample, // not supposed to be called on non-object schemas
   );
-  return dest.meta({
-    ...destMeta,
-    [metaSymbol]: { ...destMeta?.[metaSymbol], examples },
-  });
+  return dest.meta({ ...destMeta, examples }); // @todo might not be required to spread since .meta() does it now
 };
 
 export const getBrand = (subject: $ZodType) => {