json-schema-processors.js 20 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605
  1. import { extractDefs, finalize, initializeContext, process, } from "./to-json-schema.js";
  2. import { getEnumValues } from "./util.js";
  3. const formatMap = {
  4. guid: "uuid",
  5. url: "uri",
  6. datetime: "date-time",
  7. json_string: "json-string",
  8. regex: "", // do not set
  9. };
  10. // ==================== SIMPLE TYPE PROCESSORS ====================
  11. export const stringProcessor = (schema, ctx, _json, _params) => {
  12. const json = _json;
  13. json.type = "string";
  14. const { minimum, maximum, format, patterns, contentEncoding } = schema._zod
  15. .bag;
  16. if (typeof minimum === "number")
  17. json.minLength = minimum;
  18. if (typeof maximum === "number")
  19. json.maxLength = maximum;
  20. // custom pattern overrides format
  21. if (format) {
  22. json.format = formatMap[format] ?? format;
  23. if (json.format === "")
  24. delete json.format; // empty format is not valid
  25. // JSON Schema format: "time" requires a full time with offset or Z
  26. // z.iso.time() does not include timezone information, so format: "time" should never be used
  27. if (format === "time") {
  28. delete json.format;
  29. }
  30. }
  31. if (contentEncoding)
  32. json.contentEncoding = contentEncoding;
  33. if (patterns && patterns.size > 0) {
  34. const regexes = [...patterns];
  35. if (regexes.length === 1)
  36. json.pattern = regexes[0].source;
  37. else if (regexes.length > 1) {
  38. json.allOf = [
  39. ...regexes.map((regex) => ({
  40. ...(ctx.target === "draft-07" || ctx.target === "draft-04" || ctx.target === "openapi-3.0"
  41. ? { type: "string" }
  42. : {}),
  43. pattern: regex.source,
  44. })),
  45. ];
  46. }
  47. }
  48. };
  49. export const numberProcessor = (schema, ctx, _json, _params) => {
  50. const json = _json;
  51. const { minimum, maximum, format, multipleOf, exclusiveMaximum, exclusiveMinimum } = schema._zod.bag;
  52. if (typeof format === "string" && format.includes("int"))
  53. json.type = "integer";
  54. else
  55. json.type = "number";
  56. if (typeof exclusiveMinimum === "number") {
  57. if (ctx.target === "draft-04" || ctx.target === "openapi-3.0") {
  58. json.minimum = exclusiveMinimum;
  59. json.exclusiveMinimum = true;
  60. }
  61. else {
  62. json.exclusiveMinimum = exclusiveMinimum;
  63. }
  64. }
  65. if (typeof minimum === "number") {
  66. json.minimum = minimum;
  67. if (typeof exclusiveMinimum === "number" && ctx.target !== "draft-04") {
  68. if (exclusiveMinimum >= minimum)
  69. delete json.minimum;
  70. else
  71. delete json.exclusiveMinimum;
  72. }
  73. }
  74. if (typeof exclusiveMaximum === "number") {
  75. if (ctx.target === "draft-04" || ctx.target === "openapi-3.0") {
  76. json.maximum = exclusiveMaximum;
  77. json.exclusiveMaximum = true;
  78. }
  79. else {
  80. json.exclusiveMaximum = exclusiveMaximum;
  81. }
  82. }
  83. if (typeof maximum === "number") {
  84. json.maximum = maximum;
  85. if (typeof exclusiveMaximum === "number" && ctx.target !== "draft-04") {
  86. if (exclusiveMaximum <= maximum)
  87. delete json.maximum;
  88. else
  89. delete json.exclusiveMaximum;
  90. }
  91. }
  92. if (typeof multipleOf === "number")
  93. json.multipleOf = multipleOf;
  94. };
  95. export const booleanProcessor = (_schema, _ctx, json, _params) => {
  96. json.type = "boolean";
  97. };
  98. export const bigintProcessor = (_schema, ctx, _json, _params) => {
  99. if (ctx.unrepresentable === "throw") {
  100. throw new Error("BigInt cannot be represented in JSON Schema");
  101. }
  102. };
  103. export const symbolProcessor = (_schema, ctx, _json, _params) => {
  104. if (ctx.unrepresentable === "throw") {
  105. throw new Error("Symbols cannot be represented in JSON Schema");
  106. }
  107. };
  108. export const nullProcessor = (_schema, ctx, json, _params) => {
  109. if (ctx.target === "openapi-3.0") {
  110. json.type = "string";
  111. json.nullable = true;
  112. json.enum = [null];
  113. }
  114. else {
  115. json.type = "null";
  116. }
  117. };
  118. export const undefinedProcessor = (_schema, ctx, _json, _params) => {
  119. if (ctx.unrepresentable === "throw") {
  120. throw new Error("Undefined cannot be represented in JSON Schema");
  121. }
  122. };
  123. export const voidProcessor = (_schema, ctx, _json, _params) => {
  124. if (ctx.unrepresentable === "throw") {
  125. throw new Error("Void cannot be represented in JSON Schema");
  126. }
  127. };
  128. export const neverProcessor = (_schema, _ctx, json, _params) => {
  129. json.not = {};
  130. };
  131. export const anyProcessor = (_schema, _ctx, _json, _params) => {
  132. // empty schema accepts anything
  133. };
  134. export const unknownProcessor = (_schema, _ctx, _json, _params) => {
  135. // empty schema accepts anything
  136. };
  137. export const dateProcessor = (_schema, ctx, _json, _params) => {
  138. if (ctx.unrepresentable === "throw") {
  139. throw new Error("Date cannot be represented in JSON Schema");
  140. }
  141. };
  142. export const enumProcessor = (schema, _ctx, json, _params) => {
  143. const def = schema._zod.def;
  144. const values = getEnumValues(def.entries);
  145. // Number enums can have both string and number values
  146. if (values.every((v) => typeof v === "number"))
  147. json.type = "number";
  148. if (values.every((v) => typeof v === "string"))
  149. json.type = "string";
  150. json.enum = values;
  151. };
  152. export const literalProcessor = (schema, ctx, json, _params) => {
  153. const def = schema._zod.def;
  154. const vals = [];
  155. for (const val of def.values) {
  156. if (val === undefined) {
  157. if (ctx.unrepresentable === "throw") {
  158. throw new Error("Literal `undefined` cannot be represented in JSON Schema");
  159. }
  160. else {
  161. // do not add to vals
  162. }
  163. }
  164. else if (typeof val === "bigint") {
  165. if (ctx.unrepresentable === "throw") {
  166. throw new Error("BigInt literals cannot be represented in JSON Schema");
  167. }
  168. else {
  169. vals.push(Number(val));
  170. }
  171. }
  172. else {
  173. vals.push(val);
  174. }
  175. }
  176. if (vals.length === 0) {
  177. // do nothing (an undefined literal was stripped)
  178. }
  179. else if (vals.length === 1) {
  180. const val = vals[0];
  181. json.type = val === null ? "null" : typeof val;
  182. if (ctx.target === "draft-04" || ctx.target === "openapi-3.0") {
  183. json.enum = [val];
  184. }
  185. else {
  186. json.const = val;
  187. }
  188. }
  189. else {
  190. if (vals.every((v) => typeof v === "number"))
  191. json.type = "number";
  192. if (vals.every((v) => typeof v === "string"))
  193. json.type = "string";
  194. if (vals.every((v) => typeof v === "boolean"))
  195. json.type = "boolean";
  196. if (vals.every((v) => v === null))
  197. json.type = "null";
  198. json.enum = vals;
  199. }
  200. };
  201. export const nanProcessor = (_schema, ctx, _json, _params) => {
  202. if (ctx.unrepresentable === "throw") {
  203. throw new Error("NaN cannot be represented in JSON Schema");
  204. }
  205. };
  206. export const templateLiteralProcessor = (schema, _ctx, json, _params) => {
  207. const _json = json;
  208. const pattern = schema._zod.pattern;
  209. if (!pattern)
  210. throw new Error("Pattern not found in template literal");
  211. _json.type = "string";
  212. _json.pattern = pattern.source;
  213. };
  214. export const fileProcessor = (schema, _ctx, json, _params) => {
  215. const _json = json;
  216. const file = {
  217. type: "string",
  218. format: "binary",
  219. contentEncoding: "binary",
  220. };
  221. const { minimum, maximum, mime } = schema._zod.bag;
  222. if (minimum !== undefined)
  223. file.minLength = minimum;
  224. if (maximum !== undefined)
  225. file.maxLength = maximum;
  226. if (mime) {
  227. if (mime.length === 1) {
  228. file.contentMediaType = mime[0];
  229. Object.assign(_json, file);
  230. }
  231. else {
  232. Object.assign(_json, file); // shared props at root
  233. _json.anyOf = mime.map((m) => ({ contentMediaType: m })); // only contentMediaType differs
  234. }
  235. }
  236. else {
  237. Object.assign(_json, file);
  238. }
  239. };
  240. export const successProcessor = (_schema, _ctx, json, _params) => {
  241. json.type = "boolean";
  242. };
  243. export const customProcessor = (_schema, ctx, _json, _params) => {
  244. if (ctx.unrepresentable === "throw") {
  245. throw new Error("Custom types cannot be represented in JSON Schema");
  246. }
  247. };
  248. export const functionProcessor = (_schema, ctx, _json, _params) => {
  249. if (ctx.unrepresentable === "throw") {
  250. throw new Error("Function types cannot be represented in JSON Schema");
  251. }
  252. };
  253. export const transformProcessor = (_schema, ctx, _json, _params) => {
  254. if (ctx.unrepresentable === "throw") {
  255. throw new Error("Transforms cannot be represented in JSON Schema");
  256. }
  257. };
  258. export const mapProcessor = (_schema, ctx, _json, _params) => {
  259. if (ctx.unrepresentable === "throw") {
  260. throw new Error("Map cannot be represented in JSON Schema");
  261. }
  262. };
  263. export const setProcessor = (_schema, ctx, _json, _params) => {
  264. if (ctx.unrepresentable === "throw") {
  265. throw new Error("Set cannot be represented in JSON Schema");
  266. }
  267. };
  268. // ==================== COMPOSITE TYPE PROCESSORS ====================
  269. export const arrayProcessor = (schema, ctx, _json, params) => {
  270. const json = _json;
  271. const def = schema._zod.def;
  272. const { minimum, maximum } = schema._zod.bag;
  273. if (typeof minimum === "number")
  274. json.minItems = minimum;
  275. if (typeof maximum === "number")
  276. json.maxItems = maximum;
  277. json.type = "array";
  278. json.items = process(def.element, ctx, { ...params, path: [...params.path, "items"] });
  279. };
  280. export const objectProcessor = (schema, ctx, _json, params) => {
  281. const json = _json;
  282. const def = schema._zod.def;
  283. json.type = "object";
  284. json.properties = {};
  285. const shape = def.shape;
  286. for (const key in shape) {
  287. json.properties[key] = process(shape[key], ctx, {
  288. ...params,
  289. path: [...params.path, "properties", key],
  290. });
  291. }
  292. // required keys
  293. const allKeys = new Set(Object.keys(shape));
  294. const requiredKeys = new Set([...allKeys].filter((key) => {
  295. const v = def.shape[key]._zod;
  296. if (ctx.io === "input") {
  297. return v.optin === undefined;
  298. }
  299. else {
  300. return v.optout === undefined;
  301. }
  302. }));
  303. if (requiredKeys.size > 0) {
  304. json.required = Array.from(requiredKeys);
  305. }
  306. // catchall
  307. if (def.catchall?._zod.def.type === "never") {
  308. // strict
  309. json.additionalProperties = false;
  310. }
  311. else if (!def.catchall) {
  312. // regular
  313. if (ctx.io === "output")
  314. json.additionalProperties = false;
  315. }
  316. else if (def.catchall) {
  317. json.additionalProperties = process(def.catchall, ctx, {
  318. ...params,
  319. path: [...params.path, "additionalProperties"],
  320. });
  321. }
  322. };
  323. export const unionProcessor = (schema, ctx, json, params) => {
  324. const def = schema._zod.def;
  325. // Exclusive unions (inclusive === false) use oneOf (exactly one match) instead of anyOf (one or more matches)
  326. // This includes both z.xor() and discriminated unions
  327. const isExclusive = def.inclusive === false;
  328. const options = def.options.map((x, i) => process(x, ctx, {
  329. ...params,
  330. path: [...params.path, isExclusive ? "oneOf" : "anyOf", i],
  331. }));
  332. if (isExclusive) {
  333. json.oneOf = options;
  334. }
  335. else {
  336. json.anyOf = options;
  337. }
  338. };
  339. export const intersectionProcessor = (schema, ctx, json, params) => {
  340. const def = schema._zod.def;
  341. const a = process(def.left, ctx, {
  342. ...params,
  343. path: [...params.path, "allOf", 0],
  344. });
  345. const b = process(def.right, ctx, {
  346. ...params,
  347. path: [...params.path, "allOf", 1],
  348. });
  349. const isSimpleIntersection = (val) => "allOf" in val && Object.keys(val).length === 1;
  350. const allOf = [
  351. ...(isSimpleIntersection(a) ? a.allOf : [a]),
  352. ...(isSimpleIntersection(b) ? b.allOf : [b]),
  353. ];
  354. json.allOf = allOf;
  355. };
  356. export const tupleProcessor = (schema, ctx, _json, params) => {
  357. const json = _json;
  358. const def = schema._zod.def;
  359. json.type = "array";
  360. const prefixPath = ctx.target === "draft-2020-12" ? "prefixItems" : "items";
  361. const restPath = ctx.target === "draft-2020-12" ? "items" : ctx.target === "openapi-3.0" ? "items" : "additionalItems";
  362. const prefixItems = def.items.map((x, i) => process(x, ctx, {
  363. ...params,
  364. path: [...params.path, prefixPath, i],
  365. }));
  366. const rest = def.rest
  367. ? process(def.rest, ctx, {
  368. ...params,
  369. path: [...params.path, restPath, ...(ctx.target === "openapi-3.0" ? [def.items.length] : [])],
  370. })
  371. : null;
  372. if (ctx.target === "draft-2020-12") {
  373. json.prefixItems = prefixItems;
  374. if (rest) {
  375. json.items = rest;
  376. }
  377. }
  378. else if (ctx.target === "openapi-3.0") {
  379. json.items = {
  380. anyOf: prefixItems,
  381. };
  382. if (rest) {
  383. json.items.anyOf.push(rest);
  384. }
  385. json.minItems = prefixItems.length;
  386. if (!rest) {
  387. json.maxItems = prefixItems.length;
  388. }
  389. }
  390. else {
  391. json.items = prefixItems;
  392. if (rest) {
  393. json.additionalItems = rest;
  394. }
  395. }
  396. // length
  397. const { minimum, maximum } = schema._zod.bag;
  398. if (typeof minimum === "number")
  399. json.minItems = minimum;
  400. if (typeof maximum === "number")
  401. json.maxItems = maximum;
  402. };
  403. export const recordProcessor = (schema, ctx, _json, params) => {
  404. const json = _json;
  405. const def = schema._zod.def;
  406. json.type = "object";
  407. // For looseRecord with regex patterns, use patternProperties
  408. // This correctly represents "only validate keys matching the pattern" semantics
  409. // and composes well with allOf (intersections)
  410. const keyType = def.keyType;
  411. const keyBag = keyType._zod.bag;
  412. const patterns = keyBag?.patterns;
  413. if (def.mode === "loose" && patterns && patterns.size > 0) {
  414. // Use patternProperties for looseRecord with regex patterns
  415. const valueSchema = process(def.valueType, ctx, {
  416. ...params,
  417. path: [...params.path, "patternProperties", "*"],
  418. });
  419. json.patternProperties = {};
  420. for (const pattern of patterns) {
  421. json.patternProperties[pattern.source] = valueSchema;
  422. }
  423. }
  424. else {
  425. // Default behavior: use propertyNames + additionalProperties
  426. if (ctx.target === "draft-07" || ctx.target === "draft-2020-12") {
  427. json.propertyNames = process(def.keyType, ctx, {
  428. ...params,
  429. path: [...params.path, "propertyNames"],
  430. });
  431. }
  432. json.additionalProperties = process(def.valueType, ctx, {
  433. ...params,
  434. path: [...params.path, "additionalProperties"],
  435. });
  436. }
  437. // Add required for keys with discrete values (enum, literal, etc.)
  438. const keyValues = keyType._zod.values;
  439. if (keyValues) {
  440. const validKeyValues = [...keyValues].filter((v) => typeof v === "string" || typeof v === "number");
  441. if (validKeyValues.length > 0) {
  442. json.required = validKeyValues;
  443. }
  444. }
  445. };
  446. export const nullableProcessor = (schema, ctx, json, params) => {
  447. const def = schema._zod.def;
  448. const inner = process(def.innerType, ctx, params);
  449. const seen = ctx.seen.get(schema);
  450. if (ctx.target === "openapi-3.0") {
  451. seen.ref = def.innerType;
  452. json.nullable = true;
  453. }
  454. else {
  455. json.anyOf = [inner, { type: "null" }];
  456. }
  457. };
  458. export const nonoptionalProcessor = (schema, ctx, _json, params) => {
  459. const def = schema._zod.def;
  460. process(def.innerType, ctx, params);
  461. const seen = ctx.seen.get(schema);
  462. seen.ref = def.innerType;
  463. };
  464. export const defaultProcessor = (schema, ctx, json, params) => {
  465. const def = schema._zod.def;
  466. process(def.innerType, ctx, params);
  467. const seen = ctx.seen.get(schema);
  468. seen.ref = def.innerType;
  469. json.default = JSON.parse(JSON.stringify(def.defaultValue));
  470. };
  471. export const prefaultProcessor = (schema, ctx, json, params) => {
  472. const def = schema._zod.def;
  473. process(def.innerType, ctx, params);
  474. const seen = ctx.seen.get(schema);
  475. seen.ref = def.innerType;
  476. if (ctx.io === "input")
  477. json._prefault = JSON.parse(JSON.stringify(def.defaultValue));
  478. };
  479. export const catchProcessor = (schema, ctx, json, params) => {
  480. const def = schema._zod.def;
  481. process(def.innerType, ctx, params);
  482. const seen = ctx.seen.get(schema);
  483. seen.ref = def.innerType;
  484. let catchValue;
  485. try {
  486. catchValue = def.catchValue(undefined);
  487. }
  488. catch {
  489. throw new Error("Dynamic catch values are not supported in JSON Schema");
  490. }
  491. json.default = catchValue;
  492. };
  493. export const pipeProcessor = (schema, ctx, _json, params) => {
  494. const def = schema._zod.def;
  495. const innerType = ctx.io === "input" ? (def.in._zod.def.type === "transform" ? def.out : def.in) : def.out;
  496. process(innerType, ctx, params);
  497. const seen = ctx.seen.get(schema);
  498. seen.ref = innerType;
  499. };
  500. export const readonlyProcessor = (schema, ctx, json, params) => {
  501. const def = schema._zod.def;
  502. process(def.innerType, ctx, params);
  503. const seen = ctx.seen.get(schema);
  504. seen.ref = def.innerType;
  505. json.readOnly = true;
  506. };
  507. export const promiseProcessor = (schema, ctx, _json, params) => {
  508. const def = schema._zod.def;
  509. process(def.innerType, ctx, params);
  510. const seen = ctx.seen.get(schema);
  511. seen.ref = def.innerType;
  512. };
  513. export const optionalProcessor = (schema, ctx, _json, params) => {
  514. const def = schema._zod.def;
  515. process(def.innerType, ctx, params);
  516. const seen = ctx.seen.get(schema);
  517. seen.ref = def.innerType;
  518. };
  519. export const lazyProcessor = (schema, ctx, _json, params) => {
  520. const innerType = schema._zod.innerType;
  521. process(innerType, ctx, params);
  522. const seen = ctx.seen.get(schema);
  523. seen.ref = innerType;
  524. };
  525. // ==================== ALL PROCESSORS ====================
  526. export const allProcessors = {
  527. string: stringProcessor,
  528. number: numberProcessor,
  529. boolean: booleanProcessor,
  530. bigint: bigintProcessor,
  531. symbol: symbolProcessor,
  532. null: nullProcessor,
  533. undefined: undefinedProcessor,
  534. void: voidProcessor,
  535. never: neverProcessor,
  536. any: anyProcessor,
  537. unknown: unknownProcessor,
  538. date: dateProcessor,
  539. enum: enumProcessor,
  540. literal: literalProcessor,
  541. nan: nanProcessor,
  542. template_literal: templateLiteralProcessor,
  543. file: fileProcessor,
  544. success: successProcessor,
  545. custom: customProcessor,
  546. function: functionProcessor,
  547. transform: transformProcessor,
  548. map: mapProcessor,
  549. set: setProcessor,
  550. array: arrayProcessor,
  551. object: objectProcessor,
  552. union: unionProcessor,
  553. intersection: intersectionProcessor,
  554. tuple: tupleProcessor,
  555. record: recordProcessor,
  556. nullable: nullableProcessor,
  557. nonoptional: nonoptionalProcessor,
  558. default: defaultProcessor,
  559. prefault: prefaultProcessor,
  560. catch: catchProcessor,
  561. pipe: pipeProcessor,
  562. readonly: readonlyProcessor,
  563. promise: promiseProcessor,
  564. optional: optionalProcessor,
  565. lazy: lazyProcessor,
  566. };
  567. export function toJSONSchema(input, params) {
  568. if ("_idmap" in input) {
  569. // Registry case
  570. const registry = input;
  571. const ctx = initializeContext({ ...params, processors: allProcessors });
  572. const defs = {};
  573. // First pass: process all schemas to build the seen map
  574. for (const entry of registry._idmap.entries()) {
  575. const [_, schema] = entry;
  576. process(schema, ctx);
  577. }
  578. const schemas = {};
  579. const external = {
  580. registry,
  581. uri: params?.uri,
  582. defs,
  583. };
  584. // Update the context with external configuration
  585. ctx.external = external;
  586. // Second pass: emit each schema
  587. for (const entry of registry._idmap.entries()) {
  588. const [key, schema] = entry;
  589. extractDefs(ctx, schema);
  590. schemas[key] = finalize(ctx, schema);
  591. }
  592. if (Object.keys(defs).length > 0) {
  593. const defsSegment = ctx.target === "draft-2020-12" ? "$defs" : "definitions";
  594. schemas.__shared = {
  595. [defsSegment]: defs,
  596. };
  597. }
  598. return { schemas };
  599. }
  600. // Single schema case
  601. const ctx = initializeContext({ ...params, processors: allProcessors });
  602. process(input, ctx);
  603. extractDefs(ctx, input);
  604. return finalize(ctx, input);
  605. }