{"id":"168b5634da54477b","repo":"colinhacks/zod","slug":"date-cannot-be-represented-in-json-schema","errorCode":null,"errorMessage":"Date cannot be represented in JSON Schema","messagePattern":"Date 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":150,"sourceCode":"    throw new Error(\"Void cannot be represented in JSON Schema\");\n  }\n};\n\nexport const neverProcessor: Processor<schemas.$ZodNever> = (_schema, _ctx, json, _params) => {\n  json.not = {};\n};\n\nexport const anyProcessor: Processor<schemas.$ZodAny> = (_schema, _ctx, _json, _params) => {\n  // empty schema accepts anything\n};\n\nexport const unknownProcessor: Processor<schemas.$ZodUnknown> = (_schema, _ctx, _json, _params) => {\n  // empty schema accepts anything\n};\n\nexport const dateProcessor: Processor<schemas.$ZodDate> = (_schema, ctx, _json, _params) => {\n  if (ctx.unrepresentable === \"throw\") {\n    throw new Error(\"Date cannot be represented in JSON Schema\");\n  }\n};\n\nexport const enumProcessor: Processor<schemas.$ZodEnum> = (schema, _ctx, json, _params) => {\n  const def = schema._zod.def as schemas.$ZodEnumDef;\n  const values = getEnumValues(def.entries);\n  // Number enums can have both string and number values\n  if (values.every((v) => typeof v === \"number\")) json.type = \"number\";\n  if (values.every((v) => typeof v === \"string\")) json.type = \"string\";\n  json.enum = values;\n};\n\nexport const literalProcessor: Processor<schemas.$ZodLiteral> = (schema, ctx, json, _params) => {\n  const def = schema._zod.def as schemas.$ZodLiteralDef<any>;\n  const vals: (string | number | boolean | null)[] = [];\n  for (const val of def.values) {\n    if (val === undefined) {\n      if (ctx.unrepresentable === \"throw\") {","sourceCodeStart":132,"sourceCodeEnd":168,"githubUrl":"https://github.com/colinhacks/zod/blob/912f0f51b0ced654d0069741e7160834dca742ee/packages/zod/src/v4/core/json-schema-processors.ts#L132-L168","documentation":"JSON has no native date type (dates are conventionally ISO strings), so Zod will not guess a representation: `dateProcessor` (json-schema-processors.ts:148) throws for `z.date()` when `ctx.unrepresentable === \"throw\"` (default). Unlike bigint/symbol, a clean replacement exists (`z.iso.datetime()` or `z.string().datetime()`).","triggerScenarios":"`z.toJSONSchema()` over a schema containing `z.date()`, with default options. Very common in API schemas that model timestamps as JS Date objects.","commonSituations":"Generating OpenAPI for an endpoint that returns Date objects; sharing a Zod schema between a Node backend (uses Date) and a JSON Schema consumer.","solutions":["For conversion only, call `z.toJSONSchema(schema, { unrepresentable: \"any\" })`.","Preferably replace `z.date()` with `z.iso.datetime()` (or `z.string().datetime()`) so the contract uses the standard `date-time` JSON Schema format.","Keep `z.date()` at the runtime boundary and pipe/transform into a datetime string schema for the contract."],"exampleFix":"// before\nz.toJSONSchema(z.object({ createdAt: z.date() })); // throws\n// after\nz.toJSONSchema(z.object({ createdAt: z.iso.datetime() })); // -> { type: \"string\", format: \"date-time\" }","handlingStrategy":"fallback","validationCode":"// Prefer a JSON-native datetime for contract schemas.\nconst contractSchema = z.object({ createdAt: z.iso.datetime() });\nconst json = z.toJSONSchema(contractSchema);","typeGuard":"function usesDate(schema: z.ZodType): boolean {\n  return schema._zod.traits.has(\"$ZodDate\");\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":["Use `z.iso.datetime()` for any field that will be converted to JSON Schema.","Keep `z.date()` only at the runtime boundary and pipe into a datetime string for contracts.","Standardize `{ unrepresentable: \"any\" }` for mixed schemas containing dates."],"tags":["json-schema","date","unrepresentable","openapi","datetime"],"analyzedSha":"912f0f51b0ced654d0069741e7160834dca742ee","analyzedAt":"2026-08-03T17:41:55.908Z","schemaVersion":2}