@gabrielbryk/json-schema-to-zod 2.15.0 → 2.16.0

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # @gabrielbryk/json-schema-to-zod
 
+## 2.16.0
+
+### Minor Changes
+
+- 21d2701: Add `optionalStrategy` option to control whether optional object properties emit `.optional()` or `.exactOptional()`. Defaults to `"exactOptional"` (current behaviour) for full backward compatibility. Use `"optional"` when callers may produce `{ field: undefined }` via optional chaining or object spreads.
+
+## 2.15.2
+
+### Patch Changes
+
+- 21b550f: Fix recursive oneOf with direct self-references using z.union instead of z.xor
+
+  When a recursive schema has a oneOf containing a direct self-reference (without z.lazy() wrapper),
+  the v2.15.0 fix to use z.union for recursive catchall cases didn't apply because the condition
+  `isRecursive && (inCatchall || hasLazyMembers)` didn't cover direct self-references.
+
+  This patch adds detection for direct self-references in oneOf options, ensuring z.union is used
+  instead of z.xor for these patterns. z.xor validation fails during parsing when evaluating
+  self-referential branches, so z.union is the correct choice.
+
+  This fixes validation failures for schemas like EventConsumptionStrategy from the Serverless
+  Workflow spec which uses: `oneOf: [simple-cases, allOf: [$ref: self, additional-properties]]`
+
+## 2.15.1
+
+### Patch Changes
+
+- Fix recursive oneOf with direct self-references using z.union instead of z.xor
+
+  When a recursive schema has a oneOf containing a direct self-reference (without z.lazy() wrapper),
+  the v2.15.0 fix to use z.union for recursive catchall cases didn't apply because the condition
+  `isRecursive && (inCatchall || hasLazyMembers)` didn't cover direct self-references.
+
+  This patch adds detection for direct self-references in oneOf options, ensuring z.union is used
+  instead of z.xor for these patterns. z.xor validation fails during parsing when evaluating
+  self-referential branches, so z.union is the correct choice.
+
+  This fixes validation failures for schemas like EventConsumptionStrategy from the Serverless
+  Workflow spec which uses: `oneOf: [simple-cases, allOf: [$ref: self, additional-properties]]`
+
 ## 2.15.0
 
 ### Minor Changes

package/dist/parsers/parseAllOf.js

@@ -1,6 +1,6 @@
 import { parseSchema } from "./parseSchema.js";
 import { half } from "../utils/half.js";
-import { shouldUseGetter, zodExactOptional, zodIntersection, zodLooseObject, zodNever, } from "../utils/schemaRepresentation.js";
+import { shouldUseGetter, zodExactOptional, zodIntersection, zodLooseObject, zodNever, zodOptional, } from "../utils/schemaRepresentation.js";
 const originalIndexKey = "__originalIndex";
 /**
  * Check if a schema defines object properties (inline object shape) without any refs.
@@ -34,7 +34,11 @@ const parseObjectShape = (schema, refs, pathPrefix) => {
             ? schema.required.includes(key)
             : typeof propSchema === "object" && propSchema.required === true;
         const optional = !hasDefault && !required;
-        const valueRep = optional ? zodExactOptional(parsedProp) : parsedProp;
+        const valueRep = optional
+            ? refs.optionalStrategy === "optional"
+                ? zodOptional(parsedProp)
+                : zodExactOptional(parsedProp)
+            : parsedProp;
         const isGetter = shouldUseGetter(valueRep, refs.currentSchemaName, refs.cycleRefNames, refs.cycleComponentByName);
         shapeEntries.push({ key, rep: valueRep, isGetter });
     }

package/dist/parsers/parseObject.js

@@ -5,7 +5,7 @@ import { expandJsdocs } from "../utils/jsdocs.js";
 import { anyOrUnknown } from "../utils/anyOrUnknown.js";
 import { buildIntersectionTree } from "../utils/buildIntersectionTree.js";
 import { collectSchemaProperties } from "../utils/collectSchemaProperties.js";
-import { shouldUseGetter, zodCatchall, zodChain, zodExactOptional, zodLooseObject, zodLooseRecord, zodStrictObject, zodString, zodSuperRefine, } from "../utils/schemaRepresentation.js";
+import { shouldUseGetter, zodCatchall, zodChain, zodExactOptional, zodLooseObject, zodLooseRecord, zodOptional, zodStrictObject, zodString, zodSuperRefine, } from "../utils/schemaRepresentation.js";
 export function parseObject(objectSchema, refs) {
     const collectedProperties = objectSchema.allOf
         ? collectSchemaProperties(objectSchema, refs)
@@ -77,7 +77,11 @@ export function parseObject(objectSchema, refs) {
                 ? true
                 : typeof propSchema === "object" && propSchema.required === true;
             const isOptional = !hasDefault && !isRequired;
-            const valueRep = isOptional ? zodExactOptional(parsedProp) : parsedProp;
+            const valueRep = isOptional
+                ? refs.optionalStrategy === "optional"
+                    ? zodOptional(parsedProp)
+                    : zodExactOptional(parsedProp)
+                : parsedProp;
             const jsdoc = refs.withJsdocs &&
                 typeof propSchema === "object" &&
                 typeof propSchema.description === "string"

package/dist/parsers/parseOneOf.js

@@ -3,7 +3,7 @@ import { anyOrUnknown } from "../utils/anyOrUnknown.js";
 import { resolveRef } from "../utils/resolveRef.js";
 import { collectSchemaProperties } from "../utils/collectSchemaProperties.js";
 import { wrapRecursiveUnion } from "../utils/wrapRecursiveUnion.js";
-import { zodAny, zodDiscriminatedUnion, zodSuperRefine, zodUnion, zodXor, } from "../utils/schemaRepresentation.js";
+import { collectRefNames, zodAny, zodDiscriminatedUnion, zodSuperRefine, zodUnion, zodXor, } from "../utils/schemaRepresentation.js";
 /**
  * Check if a schema is a "required-only" validation constraint.
  * These are schemas that only specify `required` without defining types.
@@ -302,5 +302,11 @@ const shouldUseUnionForRecursiveOneOf = (refs, parsedSchemas) => {
     const isRecursive = current ? (refs.cycleRefNames?.has(current) ?? false) : false;
     const inCatchall = current ? (refs.catchallRefNames?.has(current) ?? false) : false;
     const hasLazyMembers = parsedSchemas.some((rep) => rep.node?.kind === "lazy");
-    return Boolean(isRecursive && (inCatchall || hasLazyMembers));
+    // Check if any option contains a direct self-reference (references the current schema).
+    // This handles cases where recursive schemas use direct references instead of z.lazy().
+    // Without z.lazy(), z.xor() validation fails on these self-referential branches.
+    const hasSelfReference = current
+        ? parsedSchemas.some((rep) => rep.node && collectRefNames(rep.node).has(current))
+        : false;
+    return Boolean(isRecursive && (inCatchall || hasLazyMembers || hasSelfReference));
 };

package/dist/types/Types.d.ts

@@ -290,6 +290,21 @@ export type Options = {
      * or schema titles.
      */
     oneOfOverrides?: Record<string, "union" | "xor">;
+    /**
+     * Controls which Zod modifier is used for optional object properties
+     * (those absent from `required` and without a `default`).
+     *
+     * - `"exactOptional"` (default): emits `.exactOptional()`.
+     *   The key must be entirely absent at runtime; a present `undefined` fails.
+     * - `"optional"`: emits `.optional()`.
+     *   The key may be present with `undefined` or absent entirely.
+     *
+     * Use `"optional"` when callers may include keys with `undefined` values,
+     * which is common when spreading objects or using optional chaining.
+     *
+     * @default "exactOptional"
+     */
+    optionalStrategy?: "exactOptional" | "optional";
     /**
      * Wrap recursive union schemas in z.lazy() to improve TypeScript inference.
      * This is useful for mutually recursive discriminated unions with optional properties.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gabrielbryk/json-schema-to-zod",
-  "version": "2.15.0",
+  "version": "2.16.0",
   "description": "Converts JSON schema objects or files into Zod schemas",
   "type": "module",
   "types": "./dist/types/index.d.ts",