{"id":"cfcb0d093649c23d","repo":"colinhacks/zod","slug":"transforms-cannot-be-represented-in-json-schema","errorCode":null,"errorMessage":"Transforms cannot be represented in JSON Schema","messagePattern":"Transforms cannot be represented in JSON Schema","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/zod/src/v4/core/json-schema-processors.ts","lineNumber":258,"sourceCode":"export const successProcessor: Processor<schemas.$ZodSuccess> = (_schema, _ctx, json, _params) => {\n  (json as JSONSchema.BooleanSchema).type = \"boolean\";\n};\n\nexport const customProcessor: Processor<schemas.$ZodCustom> = (_schema, ctx, _json, _params) => {\n  if (ctx.unrepresentable === \"throw\") {\n    throw new Error(\"Custom types cannot be represented in JSON Schema\");\n  }\n};\n\nexport const functionProcessor: Processor<schemas.$ZodFunction> = (_schema, ctx, _json, _params) => {\n  if (ctx.unrepresentable === \"throw\") {\n    throw new Error(\"Function types cannot be represented in JSON Schema\");\n  }\n};\n\nexport const transformProcessor: Processor<schemas.$ZodTransform> = (_schema, ctx, _json, _params) => {\n  if (ctx.unrepresentable === \"throw\") {\n    throw new Error(\"Transforms cannot be represented in JSON Schema\");\n  }\n};\n\nexport const mapProcessor: Processor<schemas.$ZodMap> = (_schema, ctx, _json, _params) => {\n  if (ctx.unrepresentable === \"throw\") {\n    throw new Error(\"Map cannot be represented in JSON Schema\");\n  }\n};\n\nexport const setProcessor: Processor<schemas.$ZodSet> = (_schema, ctx, _json, _params) => {\n  if (ctx.unrepresentable === \"throw\") {\n    throw new Error(\"Set cannot be represented in JSON Schema\");\n  }\n};\n\n// ==================== COMPOSITE TYPE PROCESSORS ====================\n\nexport const arrayProcessor: Processor<schemas.$ZodArray> = (schema, ctx, _json, params) => {","sourceCodeStart":240,"sourceCodeEnd":276,"githubUrl":"https://github.com/colinhacks/zod/blob/912f0f51b0ced654d0069741e7160834dca742ee/packages/zod/src/v4/core/json-schema-processors.ts#L240-L276","documentation":"A `z.transform()` changes the output type via an opaque function and has no static JSON Schema, so `transformProcessor` (json-schema-processors.ts:256) throws when `ctx.unrepresentable === \"throw\"` (default). JSON Schema describes shape, not computation.","triggerScenarios":"`z.toJSONSchema()` over a schema that pipes through `z.transform(fn)` or contains a transform node, with default options. Especially common when generating output schemas for schemas built with `.transform()`.","commonSituations":"Reusing a parse-time transform schema (e.g. `z.string().transform(s => new Date(s))`) for OpenAPI generation; converting a schema that has both validation and transformation.","solutions":["Pass `{ unrepresentable: \"any\" }` so transform nodes emit an empty schema.","Generate the contract from the input schema before the transform (use `io: \"input\"`), or keep a separate clean schema for the contract.","Replace the transform with a declarative schema (`z.iso.datetime()` instead of a manual `Date` transform) where possible."],"exampleFix":"// before\nz.toJSONSchema(z.string().transform((s) => Number(s))); // throws\n// after\nz.toJSONSchema(z.string().transform((s) => Number(s)), { unrepresentable: \"any\" });","handlingStrategy":"fallback","validationCode":"// Generate the contract from the input side of a pipe/transform.\nconst json = z.toJSONSchema(schema, { io: \"input\", unrepresentable: \"any\" });","typeGuard":"function usesTransform(schema: z.ZodType): boolean {\n  return schema._zod.traits.has(\"$ZodTransform\");\n}","tryCatchPattern":"try {\n  return z.toJSONSchema(schema);\n} catch (e) {\n  if (e instanceof Error && /cannot be represented in JSON Schema/.test(e.message)) {\n    return z.toJSONSchema(schema, { unrepresentable: \"any\" });\n  }\n  throw e;\n}","preventionTips":["Keep a clean declarative schema for contracts; apply transforms only in the runtime parse path.","Generate from `io: \"input\"` when the transform's input side is declarative.","Use `{ unrepresentable: \"any\" }` for schemas that must carry transforms."],"tags":["json-schema","transform","unrepresentable","openapi"],"analyzedSha":"912f0f51b0ced654d0069741e7160834dca742ee","analyzedAt":"2026-08-03T17:41:55.908Z","schemaVersion":2}