{"record":{"id":"33ed11f9b31c922b","repo":"colinhacks/zod","slug":"map-cannot-be-represented-in-json-schema","errorCode":null,"errorMessage":"Map cannot be represented in JSON Schema","messagePattern":"Map 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":264,"sourceCode":"    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) => {\n  const json = _json as JSONSchema.ArraySchema;\n  const def = schema._zod.def as schemas.$ZodArrayDef;\n  const { minimum, maximum } = schema._zod.bag;\n  if (typeof minimum === \"number\") json.minItems = minimum;\n  if (typeof maximum === \"number\") json.maxItems = maximum;\n","sourceCodeStart":246,"sourceCodeEnd":282,"githubUrl":"https://github.com/colinhacks/zod/blob/2d90846af918af9602e088812d63a035d47cdbe4/packages/zod/src/v4/core/json-schema-processors.ts#L246-L282","documentation":"Thrown by toJSONSchema() when a ZodMap schema (z.map(keySchema, valueSchema)) is encountered with unrepresentable 'throw' (default). JSON objects only allow string keys and have no first-class map type with per-key validation, so a typed Map cannot be faithfully expressed (especially with non-string keys).","triggerScenarios":"Calling toJSONSchema() on z.map(z.string(), z.number()) or any schema embedding a z.map(). OpenAPI generation for an API whose body uses Map.","commonSituations":"Runtime schemas that exploit Map for arbitrary-key lookups, then needing JSON Schema/OpenAPI output that downstream tooling can consume.","solutions":["Pass { unrepresentable: 'any' } to toJSONSchema() so the map field becomes {}.","Model the external contract as z.record(z.string(), valueSchema) (JSON object with string keys) and convert to/from Map at the boundary.","If keys are enumerable, use z.object({ ... }) or an enum-keyed record instead."],"exampleFix":"// before (throws)\nconst Schema = z.map(z.string(), z.number());\nz.toJSONSchema(Schema);\n\n// after (record for the JSON contract)\nconst Schema = z.record(z.string(), z.number());\nz.toJSONSchema(Schema);\n// { type: 'object', additionalProperties: { type: 'number' } }","handlingStrategy":"try-catch","validationCode":"const opts = schemaContains(schema, (s) => s._zod.def.type === 'map')\n  ? { unrepresentable: 'any' }\n  : {};\nconst json = z.toJSONSchema(schema, opts);","typeGuard":"function hasMap(schema) {\n  return schema._zod.def.type === 'map';\n}","tryCatchPattern":"try {\n  return z.toJSONSchema(schema);\n} catch (e) {\n  if (e.message === 'Map cannot be represented in JSON Schema') {\n    return z.toJSONSchema(schema, { unrepresentable: 'any' });\n  }\n  throw e;\n}","preventionTips":["Model external contracts with z.record(z.string(), valueSchema) instead of z.map().","Convert Map <-> plain object at the boundary; keep z.map() for runtime-only schemas.","Default to { unrepresentable: 'any' } when exporting models that may still use Map."],"tags":["json-schema","map","record","unrepresentable","to-json-schema"],"backgroundTag":null,"analyzedSha":"2d90846af918af9602e088812d63a035d47cdbe4","analyzedAt":"2026-08-11T01:21:44.015Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-22T11:17:16.035Z"}