@gabrielbryk/json-schema-to-zod 2.14.0 → 2.14.2

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @gabrielbryk/json-schema-to-zod
 
+## 2.14.2
+
+### Patch Changes
+
+- b4460e4: Restore getter-based recursion for named properties to preserve inferred types in recursive schemas.
+
+## 2.14.1
+
+### Patch Changes
+
+- 98f75f5: Normalize unions (dedupe/flatten, fold nullable) and balance object-level intersections for simpler output and faster type checking. Preserve base types for `not` schemas and keep required-only `oneOf` refinements from erasing base object types.
+
 ## 2.14.0
 
 ### Minor Changes

package/README.md

@@ -17,6 +17,10 @@ Since v2 the CLI supports piped JSON.
 
 _Looking for the exact opposite? Check out [zod-to-json-schema](https://npmjs.org/package/zod-to-json-schema)_
 
+## Open issues
+
+See `open-issues.md` for known correctness, type-safety, and performance gaps.
+
 ## Usage
 
 ### Online

package/dist/index.js

@@ -22,7 +22,9 @@ export * from "./parsers/parseSchema.js";
 export * from "./parsers/parseSimpleDiscriminatedOneOf.js";
 export * from "./parsers/parseString.js";
 export * from "./utils/anyOrUnknown.js";
+export * from "./utils/buildIntersectionTree.js";
 export * from "./utils/buildRefRegistry.js";
+export * from "./utils/collectSchemaProperties.js";
 export * from "./utils/cycles.js";
 export * from "./utils/esmEmitter.js";
 export * from "./utils/extractInlineObject.js";
@@ -30,6 +32,7 @@ export * from "./utils/half.js";
 export * from "./utils/jsdocs.js";
 export * from "./utils/liftInlineObjects.js";
 export * from "./utils/namingService.js";
+export * from "./utils/normalizeUnion.js";
 export * from "./utils/omit.js";
 export * from "./utils/resolveRef.js";
 export * from "./utils/resolveUri.js";

package/dist/parsers/parseAnyOf.js

@@ -1,6 +1,7 @@
 import { parseSchema } from "./parseSchema.js";
 import { anyOrUnknown } from "../utils/anyOrUnknown.js";
 import { extractInlineObject } from "../utils/extractInlineObject.js";
+import { normalizeUnionMembers } from "../utils/normalizeUnion.js";
 export const parseAnyOf = (schema, refs) => {
     if (!schema.anyOf.length) {
         return anyOrUnknown(refs);
@@ -19,8 +20,15 @@ export const parseAnyOf = (schema, refs) => {
         }
         return parseSchema(memberSchema, { ...refs, path: [...refs.path, "anyOf", i] });
     });
-    const expressions = members.map((m) => m.expression).join(", ");
-    const types = members.map((m) => m.type).join(", ");
+    const normalized = normalizeUnionMembers(members, { foldNullable: true });
+    if (normalized.length === 0) {
+        return anyOrUnknown(refs);
+    }
+    if (normalized.length === 1) {
+        return normalized[0];
+    }
+    const expressions = normalized.map((m) => m.expression).join(", ");
+    const types = normalized.map((m) => m.type).join(", ");
     const expression = `z.union([${expressions}])`;
     // Use readonly tuple for union type annotations (required for recursive type inference)
     const type = `z.ZodUnion<readonly [${types}]>`;

package/dist/parsers/parseMultipleType.js

@@ -1,8 +1,17 @@
 import { parseSchema } from "./parseSchema.js";
+import { normalizeUnionMembers } from "../utils/normalizeUnion.js";
 export const parseMultipleType = (schema, refs) => {
-    const schemas = schema.type.map((type) => parseSchema({ ...schema, type }, { ...refs, withoutDefaults: true }));
-    const expressions = schemas.map((s) => s.expression).join(", ");
-    const types = schemas.map((s) => s.type).join(", ");
+    const uniqueTypes = Array.from(new Set(schema.type));
+    const schemas = uniqueTypes.map((type) => parseSchema({ ...schema, type }, { ...refs, withoutDefaults: true }));
+    const normalized = normalizeUnionMembers(schemas, { foldNullable: true });
+    if (normalized.length === 0) {
+        return { expression: "z.never()", type: "z.ZodNever" };
+    }
+    if (normalized.length === 1) {
+        return normalized[0];
+    }
+    const expressions = normalized.map((s) => s.expression).join(", ");
+    const types = normalized.map((s) => s.type).join(", ");
     return {
         expression: `z.union([${expressions}])`,
         type: `z.ZodUnion<[${types}]>`,

package/dist/parsers/parseNot.js

@@ -1,14 +1,17 @@
 import { parseSchema } from "./parseSchema.js";
 import { anyOrUnknown } from "../utils/anyOrUnknown.js";
 export const parseNot = (schema, refs) => {
-    const baseSchema = anyOrUnknown(refs);
+    const baseSchemaInput = { ...schema };
+    delete baseSchemaInput.not;
+    const baseSchema = parseSchema(baseSchemaInput, refs, true);
+    const resolvedBase = baseSchema.expression === "z.never()" ? anyOrUnknown(refs) : baseSchema;
     const notSchema = parseSchema(schema.not, {
         ...refs,
         path: [...refs.path, "not"],
     });
     return {
-        expression: `${baseSchema.expression}.refine((value) => !${notSchema.expression}.safeParse(value).success, "Invalid input: Should NOT be valid against schema")`,
+        expression: `${resolvedBase.expression}.refine((value) => !${notSchema.expression}.safeParse(value).success, "Invalid input: Should NOT be valid against schema")`,
         // In Zod v4, .refine() doesn't change the type
-        type: baseSchema.type,
+        type: resolvedBase.type,
     };
 };

package/dist/parsers/parseObject.js

@@ -2,25 +2,81 @@ import { parseAnyOf } from "./parseAnyOf.js";
 import { parseOneOf } from "./parseOneOf.js";
 import { parseSchema } from "./parseSchema.js";
 import { addJsdocs } from "../utils/jsdocs.js";
+import { anyOrUnknown } from "../utils/anyOrUnknown.js";
+import { buildIntersectionTree } from "../utils/buildIntersectionTree.js";
+import { collectSchemaProperties } from "../utils/collectSchemaProperties.js";
+import { shouldUseGetter } from "../utils/schemaRepresentation.js";
 export function parseObject(objectSchema, refs) {
+    const collectedProperties = objectSchema.allOf
+        ? collectSchemaProperties(objectSchema, refs)
+        : undefined;
     const explicitProps = objectSchema.properties ? Object.keys(objectSchema.properties) : [];
-    const requiredProps = Array.isArray(objectSchema.required) ? objectSchema.required : [];
-    const allProps = [...new Set([...explicitProps, ...requiredProps])];
+    const collectedProps = collectedProperties ? Object.keys(collectedProperties.properties) : [];
+    const requiredProps = collectedProperties
+        ? collectedProperties.required
+        : Array.isArray(objectSchema.required)
+            ? objectSchema.required
+            : [];
+    const allProps = [...new Set([...explicitProps, ...requiredProps, ...collectedProps])];
     const hasProperties = allProps.length > 0;
+    const requiredSet = new Set(requiredProps);
+    const isPropertyOnlyAllOfMember = (member) => {
+        if (typeof member !== "object" || member === null)
+            return false;
+        const obj = member;
+        if (obj.$ref || obj.$dynamicRef)
+            return false;
+        const keys = Object.keys(obj);
+        if (keys.length === 0)
+            return false;
+        return keys.every((key) => key === "properties" || key === "required");
+    };
+    const propertyOnlyOverlapKeys = new Set();
+    const propertyOnlyKeysByIndex = new Map();
+    if (objectSchema.allOf) {
+        const keyCounts = new Map();
+        const addKey = (key) => {
+            keyCounts.set(key, (keyCounts.get(key) ?? 0) + 1);
+        };
+        for (const key of Object.keys(objectSchema.properties ?? {})) {
+            addKey(key);
+        }
+        objectSchema.allOf.forEach((member, index) => {
+            if (!isPropertyOnlyAllOfMember(member))
+                return;
+            const obj = member;
+            const keys = Object.keys(obj.properties ?? {});
+            if (keys.length) {
+                propertyOnlyKeysByIndex.set(index, keys);
+                keys.forEach(addKey);
+            }
+        });
+        for (const [key, count] of keyCounts) {
+            if (count > 1) {
+                propertyOnlyOverlapKeys.add(key);
+            }
+        }
+    }
     // 1. Process Properties (Base Object)
     let baseObjectExpr = "z.object({";
     const propertyTypes = [];
     if (hasProperties) {
         baseObjectExpr += allProps
             .map((key) => {
-            const propSchema = objectSchema.properties?.[key];
-            const parsedProp = propSchema
-                ? parseSchema(propSchema, { ...refs, path: [...refs.path, "properties", key] })
-                : { expression: "z.any()", type: "z.ZodAny" };
+            const hasDirectProp = Object.prototype.hasOwnProperty.call(objectSchema.properties ?? {}, key);
+            const propSchema = hasDirectProp
+                ? objectSchema.properties?.[key]
+                : collectedProperties?.properties[key];
+            const propPath = hasDirectProp
+                ? [...refs.path, "properties", key]
+                : (collectedProperties?.propertyPaths[key] ?? [...refs.path, "properties", key]);
+            const parsedProp = propSchema !== undefined
+                ? parseSchema(propSchema, { ...refs, path: propPath })
+                : anyOrUnknown(refs);
             const hasDefault = typeof propSchema === "object" && propSchema.default !== undefined;
             // Check "required" array from parent
-            const isRequired = Array.isArray(objectSchema.required)
-                ? objectSchema.required.includes(key)
+            const isRequired = requiredSet.has(key)
+                ? true
                 : typeof propSchema === "object" && propSchema.required === true;
             const isOptional = !hasDefault && !isRequired;
             let valueExpr = parsedProp.expression;
@@ -29,7 +85,16 @@ export function parseObject(objectSchema, refs) {
                 valueExpr = `${parsedProp.expression}.exactOptional()`;
                 valueType = `z.ZodExactOptional<${parsedProp.type}>`;
             }
+            const valueRep = { expression: valueExpr, type: valueType };
             propertyTypes.push({ key, type: valueType });
+            const useGetter = shouldUseGetter(valueRep, refs.currentSchemaName, refs.cycleRefNames, refs.cycleComponentByName);
+            if (useGetter) {
+                let result = `get ${JSON.stringify(key)}(): ${valueType} { return ${valueExpr} }`;
+                if (refs.withJsdocs && typeof propSchema === "object") {
+                    result = addJsdocs(propSchema, result);
+                }
+                return result;
+            }
             if (refs.withJsdocs && typeof propSchema === "object") {
                 valueExpr = addJsdocs(propSchema, valueExpr);
             }
@@ -75,24 +140,19 @@ export function parseObject(objectSchema, refs) {
         }
     }
     // 3. Handle patternProperties using Intersection with z.looseRecord
-    let finalExpr = baseObjectModified;
-    const intersectionTypes = [];
-    if (hasPattern) {
-        for (const [pattern, schema] of Object.entries(patternProps)) {
-            const validSchema = parseSchema(schema, {
-                ...refs,
-                path: [...refs.path, "patternProperties", pattern],
-            });
-            const keySchema = `z.string().regex(new RegExp(${JSON.stringify(pattern)}))`;
-            const recordExpr = `z.looseRecord(${keySchema}, ${validSchema.expression})`;
-            finalExpr = `z.intersection(${finalExpr}, ${recordExpr})`;
-            intersectionTypes.push(`z.ZodRecord<z.ZodString, ${validSchema.type}>`);
-        }
+    const intersectionMembers = [];
+    let baseType = "z.ZodObject<any>";
+    if (propertyTypes.length) {
+        const shape = propertyTypes.map((p) => `${JSON.stringify(p.key)}: ${p.type}`).join("; ");
+        baseType = `z.ZodObject<{${shape}}>`;
     }
+    intersectionMembers.push({ expression: baseObjectModified, type: baseType });
     // 3b. Add manual additionalProperties check if needed
+    let manualAdditionalRefine = "";
+    let oneOfRefinement = "";
     if (manualAdditionalProps) {
         const definedProps = objectSchema.properties ? Object.keys(objectSchema.properties) : [];
-        finalExpr += `.superRefine((value, ctx) => {
+        manualAdditionalRefine = `.superRefine((value, ctx) => {
   for (const key in value) {
     if (${JSON.stringify(definedProps)}.includes(key)) continue;
     let matched = false;
@@ -109,6 +169,20 @@ export function parseObject(objectSchema, refs) {
 })`;
     }
     // 4. Handle composition (allOf, oneOf, anyOf) via Intersection
+    if (hasPattern) {
+        for (const [pattern, schema] of Object.entries(patternProps)) {
+            const validSchema = parseSchema(schema, {
+                ...refs,
+                path: [...refs.path, "patternProperties", pattern],
+            });
+            const keySchema = `z.string().regex(new RegExp(${JSON.stringify(pattern)}))`;
+            const recordExpr = `z.looseRecord(${keySchema}, ${validSchema.expression})`;
+            intersectionMembers.push({
+                expression: recordExpr,
+                type: `z.ZodRecord<z.ZodString, ${validSchema.type}>`,
+            });
+        }
+    }
     if (objectSchema.allOf) {
         // Cast because we checked it exists
         const schemaWithAllOf = objectSchema;
@@ -116,24 +190,38 @@ export function parseObject(objectSchema, refs) {
         // But typically allOf implies intersection.
         // If we just use simple intersection:
         schemaWithAllOf.allOf.forEach((s, i) => {
+            if (isPropertyOnlyAllOfMember(s)) {
+                const keys = propertyOnlyKeysByIndex.get(i) ?? [];
+                const hasOverlap = keys.some((key) => propertyOnlyOverlapKeys.has(key));
+                if (!hasOverlap) {
+                    return;
+                }
+            }
             const res = parseSchema(s, { ...refs, path: [...refs.path, "allOf", i] });
-            finalExpr = `z.intersection(${finalExpr}, ${res.expression})`;
-            intersectionTypes.push(res.type);
+            intersectionMembers.push(res);
         });
     }
     if (objectSchema.oneOf) {
         const schemaWithOneOf = objectSchema;
         const res = parseOneOf(schemaWithOneOf, refs);
-        finalExpr = `z.intersection(${finalExpr}, ${res.expression})`;
-        intersectionTypes.push(res.type);
+        const refinementBody = res.refinementBody;
+        if ("isRefinementOnly" in res &&
+            res.isRefinementOnly === true &&
+            typeof refinementBody === "string") {
+            oneOfRefinement = `.superRefine(${refinementBody})`;
+        }
+        else {
+            intersectionMembers.push(res);
+        }
     }
     if (objectSchema.anyOf) {
         const schemaWithAnyOf = objectSchema;
         const res = parseAnyOf(schemaWithAnyOf, refs);
-        finalExpr = `z.intersection(${finalExpr}, ${res.expression})`;
-        intersectionTypes.push(res.type);
+        intersectionMembers.push(res);
     }
     // 5. propertyNames, unevaluatedProperties, dependentSchemas etc.
+    const final = buildIntersectionTree(intersectionMembers);
+    let finalExpr = `${final.expression}${manualAdditionalRefine}${oneOfRefinement}`;
     if (objectSchema.propertyNames) {
         const normalizedPropNames = typeof objectSchema.propertyNames === "object" &&
             objectSchema.propertyNames !== null &&
@@ -207,15 +295,7 @@ export function parseObject(objectSchema, refs) {
         }
     }
     // Calculate Type
-    let type = "z.ZodObject<any>";
-    if (propertyTypes.length) {
-        const shape = propertyTypes.map((p) => `${JSON.stringify(p.key)}: ${p.type}`).join("; ");
-        type = `z.ZodObject<{${shape}}>`;
-    }
-    // If intersections
-    intersectionTypes.forEach((t) => {
-        type = `z.ZodIntersection<${type}, ${t}>`;
-    });
+    const type = final.type;
     return {
         expression: finalExpr,
         type,

package/dist/parsers/parseOneOf.js

@@ -1,6 +1,7 @@
 import { parseSchema } from "./parseSchema.js";
 import { anyOrUnknown } from "../utils/anyOrUnknown.js";
 import { resolveRef } from "../utils/resolveRef.js";
+import { collectSchemaProperties } from "../utils/collectSchemaProperties.js";
 /**
  * Check if a schema is a "required-only" validation constraint.
  * These are schemas that only specify `required` without defining types.
@@ -49,53 +50,6 @@ const generateRequiredFieldsRefinement = (requiredCombinations) => {
         refinementBody,
     };
 };
-/**
- * Collects all properties from a schema, including properties defined in allOf members.
- * Returns merged properties object and combined required array.
- */
-const collectSchemaProperties = (schema, refs) => {
-    let properties = {};
-    let required = [];
-    // Collect direct properties
-    if (schema.properties) {
-        properties = { ...properties, ...schema.properties };
-    }
-    // Collect direct required
-    if (Array.isArray(schema.required)) {
-        required = [...required, ...schema.required];
-    }
-    // Collect from allOf members
-    if (Array.isArray(schema.allOf)) {
-        for (const member of schema.allOf) {
-            if (typeof member !== "object" || member === null)
-                continue;
-            let resolvedMember = member;
-            // Resolve $ref if needed
-            if (resolvedMember.$ref || resolvedMember.$dynamicRef) {
-                const resolved = resolveRef(resolvedMember, (resolvedMember.$ref || resolvedMember.$dynamicRef), refs);
-                if (resolved && typeof resolved.schema === "object" && resolved.schema !== null) {
-                    resolvedMember = resolved.schema;
-                }
-                else {
-                    continue;
-                }
-            }
-            // Merge properties from this allOf member
-            if (resolvedMember.properties) {
-                properties = { ...properties, ...resolvedMember.properties };
-            }
-            // Merge required from this allOf member
-            if (Array.isArray(resolvedMember.required)) {
-                required = [...required, ...resolvedMember.required];
-            }
-        }
-    }
-    // Return undefined if no properties found
-    if (Object.keys(properties).length === 0) {
-        return undefined;
-    }
-    return { properties, required: [...new Set(required)] };
-};
 /**
  * Check if two sets contain the same elements.
  */

package/dist/parsers/parseSchema.js

@@ -126,28 +126,36 @@ const parseRef = (schema, refs) => {
     // Check if this is a true forward reference (target not yet declared)
     // We only need z.lazy() for forward refs, not for back-refs to already-declared schemas
     const isForwardRef = refs.inProgress.has(refName);
-    // Check context: are we inside an object property where getters work?
-    // IMPORTANT: additionalProperties becomes z.record() (or .catchall()) which does NOT support getters for deferred evaluation
-    // Only named properties (properties, patternProperties) can use getters
+    // Check context: are we inside a named object property where getters work?
+    // IMPORTANT: additionalProperties/patternProperties become z.record() (or .catchall())
+    // and do NOT support getters for deferred evaluation.
+    const inNamedProperty = refs.path.includes("properties");
     // additionalProperties becomes z.record() value - getters don't work there
     // Per Zod issue #4881: z.record() with recursive values REQUIRES z.lazy()
-    // We also force ZodTypeAny here to break TypeScript circular inference loops
     const inRecordContext = refs.path.includes("additionalProperties");
-    // For recursive refs, use ZodTypeAny to avoid TypeScript circular inference errors ("implicitly has type 'any'")
-    // User feedback: relying on ZodTypeAny loses type safety. We will try to rely on inference or ZodType<unknown>.
-    // However, TS 4.x/5.x often requires explicit type for recursive inferred types.
-    // Zod documentation recommends: z.ZodType<MyType> = z.lazy(...)
-    // Since we don't have the named type available here easily, we rely on inference by removing the generic.
-    const isRecursive = isSameCycle || isForwardRef || refName === refs.currentSchemaName;
-    const refType = isRecursive || inRecordContext ? "z.ZodTypeAny" : `typeof ${refName}`;
+    const isSelfRecursion = refName === refs.currentSchemaName;
+    const isRecursive = isSameCycle || isForwardRef || isSelfRecursion;
+    const refType = `typeof ${refName}`;
     // Use deferred/lazy logic if recursive or in a context that requires it (record/catchall)
-    if (isRecursive || inRecordContext) {
-        // We MUST use z.lazy() for ANY recursive reference, even in named properties given that z.object() is eager.
-        // The previous optimization (skipping lazy for named properties) caused TDZ errors because getters on the arg object are evaluated immediately.
-        return {
-            expression: `z.lazy(() => ${refName})`,
-            type: `z.ZodLazy<${refType}>`,
-        };
+    if (isRecursive) {
+        const needsLazy = isForwardRef || inRecordContext || !inNamedProperty;
+        // Self-recursion in named object properties: use direct ref (getter handles deferred eval)
+        if (inNamedProperty && isSelfRecursion) {
+            return { expression: refName, type: refType };
+        }
+        // Cross-schema refs in named object properties within same cycle: use direct ref
+        // The getter in parseObject.ts will handle deferred evaluation
+        if (inNamedProperty && isSameCycle && !isForwardRef) {
+            return { expression: refName, type: refType };
+        }
+        if (needsLazy) {
+            // z.record() values with recursive refs MUST use z.lazy() (Colin confirmed in #4881)
+            // Also arrays, unions, and other non-object contexts with forward refs need z.lazy()
+            return {
+                expression: `z.lazy(() => ${refName})`,
+                type: `z.ZodLazy<${refType}>`,
+            };
+        }
     }
     return { expression: refName, type: refType };
 };

package/dist/types/index.d.ts

@@ -22,7 +22,9 @@ export * from "./parsers/parseSchema.js";
 export * from "./parsers/parseSimpleDiscriminatedOneOf.js";
 export * from "./parsers/parseString.js";
 export * from "./utils/anyOrUnknown.js";
+export * from "./utils/buildIntersectionTree.js";
 export * from "./utils/buildRefRegistry.js";
+export * from "./utils/collectSchemaProperties.js";
 export * from "./utils/cycles.js";
 export * from "./utils/esmEmitter.js";
 export * from "./utils/extractInlineObject.js";
@@ -30,6 +32,7 @@ export * from "./utils/half.js";
 export * from "./utils/jsdocs.js";
 export * from "./utils/liftInlineObjects.js";
 export * from "./utils/namingService.js";
+export * from "./utils/normalizeUnion.js";
 export * from "./utils/omit.js";
 export * from "./utils/resolveRef.js";
 export * from "./utils/resolveUri.js";

package/dist/types/utils/buildIntersectionTree.d.ts

@@ -0,0 +1,2 @@
+import { SchemaRepresentation } from "../Types.js";
+export declare const buildIntersectionTree: (members: SchemaRepresentation[]) => SchemaRepresentation;

package/dist/types/utils/collectSchemaProperties.d.ts

@@ -0,0 +1,11 @@
+import { JsonSchemaObject, JsonSchema, Refs } from "../Types.js";
+export type CollectedSchemaProperties = {
+    properties: Record<string, JsonSchema>;
+    required: string[];
+    propertyPaths: Record<string, (string | number)[]>;
+};
+/**
+ * Collects all properties from a schema, including properties defined in allOf members.
+ * Returns merged properties object, combined required array, and property source paths.
+ */
+export declare const collectSchemaProperties: (schema: JsonSchemaObject, refs: Refs) => CollectedSchemaProperties | undefined;

package/dist/types/utils/normalizeUnion.d.ts

@@ -0,0 +1,6 @@
+import type { SchemaRepresentation } from "../Types.js";
+type NormalizeUnionOptions = {
+    foldNullable?: boolean;
+};
+export declare const normalizeUnionMembers: (members: SchemaRepresentation[], options?: NormalizeUnionOptions) => SchemaRepresentation[];
+export {};

package/dist/utils/buildIntersectionTree.js

@@ -0,0 +1,23 @@
+import { half } from "./half.js";
+export const buildIntersectionTree = (members) => {
+    if (members.length === 0) {
+        return { expression: "z.never()", type: "z.ZodNever" };
+    }
+    if (members.length === 1) {
+        return members[0];
+    }
+    if (members.length === 2) {
+        const [left, right] = members;
+        return {
+            expression: `z.intersection(${left.expression}, ${right.expression})`,
+            type: `z.ZodIntersection<${left.type}, ${right.type}>`,
+        };
+    }
+    const [leftItems, rightItems] = half(members);
+    const left = buildIntersectionTree(leftItems);
+    const right = buildIntersectionTree(rightItems);
+    return {
+        expression: `z.intersection(${left.expression}, ${right.expression})`,
+        type: `z.ZodIntersection<${left.type}, ${right.type}>`,
+    };
+};

package/dist/utils/collectSchemaProperties.js

@@ -0,0 +1,55 @@
+import { resolveRef } from "./resolveRef.js";
+const mergeProperties = (target, targetPaths, props, basePath) => {
+    for (const [key, schema] of Object.entries(props)) {
+        if (!(key in target)) {
+            target[key] = schema;
+            targetPaths[key] = [...basePath, "properties", key];
+        }
+    }
+};
+/**
+ * Collects all properties from a schema, including properties defined in allOf members.
+ * Returns merged properties object, combined required array, and property source paths.
+ */
+export const collectSchemaProperties = (schema, refs) => {
+    let properties = {};
+    let required = [];
+    const propertyPaths = {};
+    // Collect direct properties
+    if (schema.properties) {
+        mergeProperties(properties, propertyPaths, schema.properties, refs.path);
+    }
+    // Collect direct required
+    if (Array.isArray(schema.required)) {
+        required = [...required, ...schema.required];
+    }
+    // Collect from allOf members
+    if (Array.isArray(schema.allOf)) {
+        schema.allOf.forEach((member, index) => {
+            if (typeof member !== "object" || member === null)
+                return;
+            let resolvedMember = member;
+            let memberPath = [...refs.path, "allOf", index];
+            if (resolvedMember.$ref || resolvedMember.$dynamicRef) {
+                const resolved = resolveRef(resolvedMember, (resolvedMember.$ref || resolvedMember.$dynamicRef), refs);
+                if (resolved && typeof resolved.schema === "object" && resolved.schema !== null) {
+                    resolvedMember = resolved.schema;
+                    memberPath = resolved.path;
+                }
+                else {
+                    return;
+                }
+            }
+            if (resolvedMember.properties) {
+                mergeProperties(properties, propertyPaths, resolvedMember.properties, memberPath);
+            }
+            if (Array.isArray(resolvedMember.required)) {
+                required = [...required, ...resolvedMember.required];
+            }
+        });
+    }
+    if (Object.keys(properties).length === 0) {
+        return undefined;
+    }
+    return { properties, required: [...new Set(required)], propertyPaths };
+};

package/dist/utils/normalizeUnion.js

@@ -0,0 +1,132 @@
+const unionPrefix = "z.union([";
+const unionSuffix = "])";
+const splitTopLevelList = (input, options) => {
+    const parts = [];
+    let current = "";
+    let depth = 0;
+    let angleDepth = 0;
+    let inString = null;
+    let escapeNext = false;
+    for (let i = 0; i < input.length; i += 1) {
+        const char = input[i];
+        if (escapeNext) {
+            current += char;
+            escapeNext = false;
+            continue;
+        }
+        if (inString) {
+            current += char;
+            if (char === "\\") {
+                escapeNext = true;
+            }
+            else if (char === inString) {
+                inString = null;
+            }
+            continue;
+        }
+        if (char === "'" || char === '"' || char === "`") {
+            inString = char;
+            current += char;
+            continue;
+        }
+        if (char === "(" || char === "[" || char === "{") {
+            depth += 1;
+            current += char;
+            continue;
+        }
+        if (char === ")" || char === "]" || char === "}") {
+            depth -= 1;
+            current += char;
+            continue;
+        }
+        if (options?.includeAngles) {
+            if (char === "<") {
+                angleDepth += 1;
+                current += char;
+                continue;
+            }
+            if (char === ">") {
+                angleDepth -= 1;
+                current += char;
+                continue;
+            }
+        }
+        if (char === "," && depth === 0 && angleDepth === 0) {
+            parts.push(current.trim());
+            current = "";
+            continue;
+        }
+        current += char;
+    }
+    if (current.trim().length > 0) {
+        parts.push(current.trim());
+    }
+    return parts;
+};
+const isPlainUnionExpression = (expression) => expression.startsWith(unionPrefix) && expression.endsWith(unionSuffix);
+const isPlainUnionType = (type) => type.startsWith("z.ZodUnion<") && type.endsWith(">");
+const extractUnionMembers = (rep) => {
+    if (!isPlainUnionExpression(rep.expression) || !isPlainUnionType(rep.type)) {
+        return undefined;
+    }
+    const exprInner = rep.expression.slice(unionPrefix.length, -unionSuffix.length).trim();
+    if (!exprInner)
+        return undefined;
+    const typeStart = rep.type.indexOf("[");
+    const typeEnd = rep.type.lastIndexOf("]");
+    if (typeStart === -1 || typeEnd === -1 || typeEnd <= typeStart) {
+        return undefined;
+    }
+    const typeInner = rep.type.slice(typeStart + 1, typeEnd).trim();
+    if (!typeInner)
+        return undefined;
+    const expressions = splitTopLevelList(exprInner);
+    const types = splitTopLevelList(typeInner, { includeAngles: true });
+    if (expressions.length === 0 || expressions.length !== types.length) {
+        return undefined;
+    }
+    return expressions.map((expression, index) => ({
+        expression,
+        type: types[index] ?? "z.ZodTypeAny",
+    }));
+};
+const isPlainNull = (rep) => rep.expression === "z.null()" && rep.type === "z.ZodNull";
+const isNullable = (rep) => rep.expression.endsWith(".nullable()") || rep.type.startsWith("z.ZodNullable<");
+const makeNullable = (rep) => {
+    if (isNullable(rep))
+        return rep;
+    return {
+        expression: `${rep.expression}.nullable()`,
+        type: `z.ZodNullable<${rep.type}>`,
+    };
+};
+export const normalizeUnionMembers = (members, options) => {
+    const flattened = [];
+    for (const member of members) {
+        const extracted = extractUnionMembers(member);
+        if (extracted) {
+            flattened.push(...extracted);
+        }
+        else {
+            flattened.push(member);
+        }
+    }
+    const seen = new Set();
+    const unique = [];
+    for (const member of flattened) {
+        if (seen.has(member.expression))
+            continue;
+        seen.add(member.expression);
+        unique.push(member);
+    }
+    if (options?.foldNullable) {
+        const nullIndex = unique.findIndex(isPlainNull);
+        if (nullIndex !== -1) {
+            const nonNull = unique.filter((_, index) => index !== nullIndex);
+            if (nonNull.length === 1) {
+                return [makeNullable(nonNull[0])];
+            }
+        }
+    }
+    return unique;
+};

package/dist/utils/schemaRepresentation.js

@@ -519,6 +519,10 @@ export const shouldUseGetter = (rep, currentSchemaName, cycleRefNames, cycleComp
     // Check if the expression directly references the current schema (self-recursion)
     if (rep.expression === currentSchemaName)
         return true;
+    // Handle wrappers like .exactOptional() or z.lazy(() => RefName)
+    const selfRefPattern = new RegExp(`\\b${currentSchemaName}\\b`);
+    if (selfRefPattern.test(rep.expression))
+        return true;
     // Check if expression contains a reference to a cycle member in the same SCC
     if (!cycleRefNames || cycleRefNames.size === 0)
         return false;

package/docs/zod-from-json-schema-research.md

@@ -0,0 +1,260 @@
+# Zod v4 native JSON Schema -> Zod conversion (fromJSONSchema)
+
+This document captures how Zod implements its native JSON Schema to Zod conversion in v4, based on the local repo at `/Users/gbryk/Repos/zod`. It focuses on the concrete implementation in `from-json-schema.ts` and the related tests/docs, and then compares it to our `json-schema-to-zod` approach.
+
+## Scope and sources
+
+Primary implementation:
+
+- Zod v4 classic converter: `packages/zod/src/v4/classic/from-json-schema.ts`.
+- Export surface: `packages/zod/src/v4/classic/external.ts` (re-exports `fromJSONSchema`).
+- Docs: `packages/docs/content/json-schema.mdx`.
+- Tests: `packages/zod/src/v4/classic/tests/from-json-schema.test.ts`.
+
+Our repo reference points (for comparison):
+
+- Entry: `src/jsonSchemaToZod.ts`.
+- Analysis pass + cycle detection: `src/core/analyzeSchema.ts`.
+- Parsing: `src/parsers/parseSchema.ts`, `src/parsers/parseObject.ts`, `src/parsers/parseAllOf.ts`, `src/parsers/parseAnyOf.ts`, `src/parsers/parseOneOf.ts`.
+- allOf property collection: `src/utils/collectSchemaProperties.ts`.
+- Ref resolution and external registry: `src/utils/resolveRef.ts`.
+- Emission: `src/core/emitZod.ts`.
+
+## High-level architecture (Zod)
+
+Zod's native converter is runtime-only and returns a `ZodType` instance, not generated source code. The entire pipeline is implemented in `from-json-schema.ts` and follows this flow:
+
+1. `fromJSONSchema(...)` handles boolean schemas and creates a conversion context. (`packages/zod/src/v4/classic/from-json-schema.ts:622-642`)
+2. Version detection uses `$schema` with a default fallback. (`packages/zod/src/v4/classic/from-json-schema.ts:104-119`)
+3. The converter calls `convertSchema(...)`, which:
+   - Builds the base schema ignoring composition keywords via `convertBaseSchema(...)`.
+   - Applies composition (anyOf/oneOf/allOf) after the base schema is built.
+   - Applies OpenAPI `nullable`, `readOnly`.
+   - Captures metadata for unknown keys in a registry. (`packages/zod/src/v4/classic/from-json-schema.ts:541-616`)
+
+The converter uses a local `z` object to avoid circular dependencies with `../index.js` by directly spreading internal module exports. (`packages/zod/src/v4/classic/from-json-schema.ts:8-13`)
+
+## Entry point and conversion context
+
+### fromJSONSchema
+
+- Entry point: `fromJSONSchema(schema, params)` in `packages/zod/src/v4/classic/from-json-schema.ts:622-642`.
+- Boolean schema handling:
+  - `true` => `z.any()`.
+  - `false` => `z.never()`.
+- Builds a `ConversionContext` with:
+  - `version`: draft-2020-12, draft-7, draft-4, or openapi-3.0.
+  - `defs`: `$defs` or `definitions` map.
+  - `refs`: cache of resolved refs.
+  - `processing`: cycle detection set.
+  - `rootSchema` and `registry`.
+
+### Version detection
+
+- `detectVersion` reads `$schema` and maps known draft URLs; otherwise defaults to draft-2020-12 unless `defaultTarget` is set. (`packages/zod/src/v4/classic/from-json-schema.ts:104-119`)
+
+## Ref handling and cycles (Zod)
+
+### resolveRef
+
+- Only local refs are supported. Any `$ref` not starting with `#` throws an error. (`packages/zod/src/v4/classic/from-json-schema.ts:121-124`)
+- Ref targets are limited to `$defs` (draft-2020-12) or `definitions` (draft-7/4) only. (`packages/zod/src/v4/classic/from-json-schema.ts:133-141`)
+- `#` by itself references the root schema. (`packages/zod/src/v4/classic/from-json-schema.ts:128-131`)
+
+### Cycle handling
+
+- When a `$ref` is encountered, `convertBaseSchema`:
+  - Returns cached value if already resolved.
+  - Detects an in-flight ref via `processing` and returns `z.lazy(...)` to break cycles. (`packages/zod/src/v4/classic/from-json-schema.ts:169-183`)
+  - Otherwise resolves the ref and stores the resulting Zod schema in `refs` cache. (`packages/zod/src/v4/classic/from-json-schema.ts:185-190`)
+
+There is no explicit graph analysis. Cycle handling is purely on the `$ref` resolution stack.
+
+## Unsupported keywords and error strategy
+
+Zod refuses some schema keywords outright by throwing errors in `convertBaseSchema`:
+
+- `not` (except `{ not: {} }` which becomes `z.never()`). (`packages/zod/src/v4/classic/from-json-schema.ts:146-154`)
+- `unevaluatedItems`, `unevaluatedProperties`. (`packages/zod/src/v4/classic/from-json-schema.ts:155-160`)
+- `if/then/else`. (`packages/zod/src/v4/classic/from-json-schema.ts:161-163`)
+- `dependentSchemas` and `dependentRequired`. (`packages/zod/src/v4/classic/from-json-schema.ts:164-165`)
+
+This means Zod's converter is intentionally partial and avoids emulating these features with refinements.
+
+## Base schema conversion (convertBaseSchema)
+
+### Enum and const
+
+- `enum` cases:
+  - Empty enum => `z.never()`.
+  - Single value => `z.literal(value)`.
+  - String-only enums => `z.enum([...])`.
+  - Mixed types => `z.union` of literals.
+  - OpenAPI nullable + enum `[null]` special-case returns `z.null()`. (`packages/zod/src/v4/classic/from-json-schema.ts:193-226`)
+- `const` => `z.literal(schema.const)` (`packages/zod/src/v4/classic/from-json-schema.ts:229-231`)
+
+### Type arrays
+
+- If `type` is an array, it is expanded into a union by cloning the schema per type. (`packages/zod/src/v4/classic/from-json-schema.ts:237-249`)
+
+### No explicit type
+
+- If `type` is missing, Zod returns `z.any()`. (`packages/zod/src/v4/classic/from-json-schema.ts:252-255`)
+
+### Strings
+
+- String format mapping uses `.check(...)` with Zod validators for a fixed set of formats: email, url/uri-reference, uuid/guid, date-time/date/time/duration, ipv4/ipv6, mac, cidr, base64, base64url, e164, jwt, emoji, nanoid, cuid/cuid2/ulid/xid/ksuid. (`packages/zod/src/v4/classic/from-json-schema.ts:263-313`)
+- Constraints:
+  - `minLength` => `.min(...)`.
+  - `maxLength` => `.max(...)`.
+  - `pattern` => `.regex(new RegExp(...))` (no implicit anchors). (`packages/zod/src/v4/classic/from-json-schema.ts:318-327`)
+
+### Numbers and integers
+
+- Integer => `z.number().int()`; number => `z.number()`.
+- Constraints: `minimum`, `maximum`, `exclusiveMinimum`, `exclusiveMaximum`, `multipleOf`. (`packages/zod/src/v4/classic/from-json-schema.ts:334-356`)
+
+### Boolean and null
+
+- `boolean` => `z.boolean()`.
+- `null` => `z.null()`. (`packages/zod/src/v4/classic/from-json-schema.ts:363-370`)
+
+### Objects
+
+- Properties are converted to a Zod shape; optionality is based on `required` only. (`packages/zod/src/v4/classic/from-json-schema.ts:373-383`)
+- `propertyNames`:
+  - If there are no properties, it becomes `z.record(keySchema, valueSchema)`.
+  - Otherwise it intersects `z.object(shape).passthrough()` with `z.looseRecord(keySchema, valueSchema)`. (`packages/zod/src/v4/classic/from-json-schema.ts:385-403`)
+- `patternProperties`:
+  - Produces a chain of `z.intersection(...)` with `z.looseRecord` for each pattern. (`packages/zod/src/v4/classic/from-json-schema.ts:406-439`)
+- `additionalProperties`:
+  - `false` => `object.strict()`.
+  - schema => `object.catchall(schema)`.
+  - `true` or omitted => `object.passthrough()`. (`packages/zod/src/v4/classic/from-json-schema.ts:443-456`)
+
+### Arrays
+
+- Tuples:
+  - Draft 2020-12 uses `prefixItems`; draft-7 uses `items` array.
+  - Additional items use `items` (2020-12) or `additionalItems` (draft-7).
+  - `minItems`/`maxItems` applied to tuples via `.check(z.minLength/maxLength)`.
+  - Implementation uses `z.tuple(...).rest(...)`. (`packages/zod/src/v4/classic/from-json-schema.ts:467-505`)
+- Regular arrays:
+  - `items` => `z.array(items)` with min/max constraints.
+  - Missing items => `z.array(z.any())`. (`packages/zod/src/v4/classic/from-json-schema.ts:505-521`)
+- `uniqueItems`, `contains`, `minContains`, `maxContains` are explicitly TODO (unsupported). (`packages/zod/src/v4/classic/from-json-schema.ts:460-462`)
+
+### Description and default
+
+- `description` => `.describe(...)`.
+- `default` => `.default(...)`. (`packages/zod/src/v4/classic/from-json-schema.ts:530-536`)
+
+## Composition (anyOf, oneOf, allOf)
+
+Composition is applied after base conversion in `convertSchema`:
+
+- `anyOf` => `z.union([...])`. (`packages/zod/src/v4/classic/from-json-schema.ts:552-556`)
+- `oneOf` => `z.xor([...])` (exclusive union). (`packages/zod/src/v4/classic/from-json-schema.ts:558-563`)
+- `allOf` => chain of `z.intersection(...)`. (`packages/zod/src/v4/classic/from-json-schema.ts:565-575`)
+
+If the schema also has an explicit type/enum/const, the base schema is intersected with the composition. Otherwise the composition becomes the base result. (`packages/zod/src/v4/classic/from-json-schema.ts:546-575`)
+
+### Empty allOf behavior
+
+- No explicit type + empty `allOf` => `z.any()`.
+- Explicit type + empty `allOf` => base schema only. (`packages/zod/src/v4/classic/from-json-schema.ts:566-575`)
+
+## OpenAPI extensions
+
+- `nullable` (OpenAPI 3.0 only) => `z.nullable(...)`. (`packages/zod/src/v4/classic/from-json-schema.ts:579-582`)
+- `readOnly` => `z.readonly(...)`. (`packages/zod/src/v4/classic/from-json-schema.ts:584-587`)
+
+## Metadata capture
+
+- Zod collects additional metadata using a registry. It builds a `extraMeta` object with:
+  - Core schema ID keys: `$id`, `id`, `$comment`, `$anchor`, `$vocabulary`, `$dynamicRef`, `$dynamicAnchor`.
+  - Content keywords: `contentEncoding`, `contentMediaType`, `contentSchema`.
+  - Any unrecognized keys (i.e., keys not in `RECOGNIZED_KEYS`). (`packages/zod/src/v4/classic/from-json-schema.ts:589-616`)
+- Those metadata are attached via `ctx.registry.add(baseSchema, extraMeta)`. (`packages/zod/src/v4/classic/from-json-schema.ts:615-616`)
+- The recognized key set is defined in `RECOGNIZED_KEYS` (`packages/zod/src/v4/classic/from-json-schema.ts:31-102`).
+
+## Test coverage signals
+
+The following tests illustrate intended behaviors:
+
+- anyOf/oneOf/allOf and empty allOf handling: `packages/zod/src/v4/classic/tests/from-json-schema.test.ts:162-205`.
+- Intersection behavior with explicit type: `packages/zod/src/v4/classic/tests/from-json-schema.test.ts:210-242`.
+
+These tests confirm the “base schema then composition” strategy and the exclusive `oneOf` behavior.
+
+## Differences vs our json-schema-to-zod implementation
+
+### Output model
+
+- Zod returns runtime `ZodType` instances (`fromJSONSchema`). (`packages/zod/src/v4/classic/from-json-schema.ts:622-642`)
+- Our converter emits TypeScript source code strings. (`src/jsonSchemaToZod.ts:1-20`, `src/core/emitZod.ts:1-120`)
+
+### Pipeline
+
+- Zod uses a single conversion pipeline with a local cache and recursion handling.
+- Our converter uses a two-pass analysis for declarations, deps, and cycles, then a separate emission pass. (`src/core/analyzeSchema.ts:39-153`, `src/core/emitZod.ts:1-120`)
+
+### Ref resolution
+
+- Zod only supports local refs under `#/$defs` or `#/definitions` and throws on external refs. (`packages/zod/src/v4/classic/from-json-schema.ts:121-143`)
+- Our converter supports `$ref`, `$dynamicRef`, `$recursiveRef`, dynamic anchors, and can load external schemas into a registry. (`src/utils/resolveRef.ts:14-138`)
+
+### Object + required + allOf
+
+- Zod does not merge `allOf` properties into a base object. Required properties are only applied to keys defined in `properties` on the current schema. (`packages/zod/src/v4/classic/from-json-schema.ts:373-383`)
+- Our `parseObject` collects properties from `allOf` (including ref targets) via `collectSchemaProperties` and uses those to avoid `any` for required-but-missing keys. (`src/parsers/parseObject.ts:14-41`, `src/utils/collectSchemaProperties.ts:24-83`)
+
+This is the same class of issue described in `/private/tmp/workflow-schema-any-issue.md` (required key defined only in allOf). Zod’s converter would not enforce such a property at the base object level; it relies on `allOf` intersection to validate the property instead.
+
+### Composition logic
+
+- Zod: `anyOf` => union, `oneOf` => xor, `allOf` => intersection, always applied after base conversion. (`packages/zod/src/v4/classic/from-json-schema.ts:541-575`)
+- Ours:
+  - `anyOf` uses union but may lift inline objects to top-level declarations. (`src/parsers/parseAnyOf.ts:17-41`)
+  - `oneOf` supports discriminated-union detection and "required-only" oneOf refinements. (`src/parsers/parseOneOf.ts:12-170`)
+  - `allOf` may use a spread merge optimization for inline object-only allOf, otherwise intersection. (`src/parsers/parseAllOf.ts:64-147`)
+
+### Keyword support
+
+- Zod throws on `not`, `if/then/else`, `dependentSchemas`, `dependentRequired`, `unevaluated*`. (`packages/zod/src/v4/classic/from-json-schema.ts:146-165`)
+- Our converter implements `not` and `if/then/else` using `refine`/`superRefine` and supports dependent schemas/required with additional refinements. (`src/parsers/parseNot.ts:1-17`, `src/parsers/parseIfThenElse.ts:1-36`, `src/parsers/parseObject.ts:209-257`)
+
+### Arrays
+
+- Zod does not implement `uniqueItems` or `contains` constraints in conversion. (`packages/zod/src/v4/classic/from-json-schema.ts:460-462`)
+- Our converter implements `uniqueItems` and `contains` with `superRefine`. (`src/parsers/parseArray.ts:58-170`)
+
+### String format coverage
+
+- Zod supports a fixed list of formats and ignores custom ones. (`packages/zod/src/v4/classic/from-json-schema.ts:263-313`)
+- Our converter maps additional formats and implements custom refinements for formats like `ip`, `hostname`, `uri-reference`, etc. (`src/parsers/parseString.ts:12-156`)
+
+### Metadata
+
+- Zod stores extra metadata in a registry and does not modify the schema via `meta()` calls directly. (`packages/zod/src/v4/classic/from-json-schema.ts:589-616`)
+- Our converter emits `.describe(...)` and `.meta(...)` calls with a curated allowlist for known keywords. (`src/parsers/parseSchema.ts:203-257`)
+
+## Implications for the current bug class
+
+The issue in `/private/tmp/workflow-schema-any-issue.md` (required keys defined in allOf) is a pattern Zod does not explicitly handle in base object conversion. Zod expects the allOf intersection to enforce those requirements, but it does not rewrite the base object shape to include those properties.
+
+Our converter attempts to merge properties from allOf into the base object shape to avoid falling back to `z.any()` for required-but-missing keys. This is implemented in `collectSchemaProperties` and used in `parseObject` (`src/utils/collectSchemaProperties.ts:24-83`, `src/parsers/parseObject.ts:14-41`).
+
+If we want to align more with Zod’s approach, we would rely on allOf intersections exclusively. If we want stronger typing and explicit properties, we should keep (and expand) our merge strategy but make sure it is comprehensive (e.g., also consider `oneOf`/`anyOf` property merges where they are structurally safe).
+
+## Potential comparison checklist for further analysis
+
+If you want a more systematic parity report, these are the main axes to evaluate between Zod and our implementation:
+
+- $ref support: local-only vs registry-based with external resolution.
+- Cycle handling: lazy from ref stack vs full cycle graph detection and two-pass parse.
+- Composition ordering: base then composition (Zod) vs parser-first composition rules (ours).
+- Required + allOf property merging: absent in Zod, present in our parseObject.
+- Conditional schemas: Zod throws; we emulate.
+- Unsupported keywords: Zod throws on more features; we implement in refinement.
+- Metadata strategy: registry vs emitted `.meta()`/`.describe()`.

package/open-issues.md

@@ -0,0 +1,140 @@
+# Open Issues
+
+Standard issue format (use for all entries):
+
+```
+## [Title]
+- Status: open | investigating | blocked | fixed
+- Category: correctness | type-safety | performance | ergonomics
+- Summary: <1–2 sentences>
+- Evidence: <file:line or schema path>
+- Impact: <who/what is affected>
+- Proposed fix: <short plan>
+- Related: <issue titles>
+- Depends on: <issue titles>
+- Notes: <optional>
+```
+
+## [unevaluatedProperties is ignored]
+
+- Status: open
+- Category: correctness
+- Summary: `unevaluatedProperties: false` is not enforced, so many generated objects are looser than the schema requires.
+- Evidence: `test/fixtures/workflow.yaml` (multiple occurrences); `src/parsers/parseObject.ts` has no handling; example output `ListenTaskSchema` in `.tmp-workflow-schema-output.ts:1827` uses `z.looseObject`.
+- Impact: Extra keys pass validation and types remain open, diverging from the JSON Schema contract.
+- Proposed fix: Implement `unevaluatedProperties` handling in `parseObject` (at least for non-composed objects; consider strategy for `allOf/oneOf/anyOf`).
+- Related: minProperties/maxProperties are not enforced; Default openness (fallbacks + passthrough) is not configurable
+- Depends on: —
+- Notes: A phased implementation can trade strictness for runtime/type complexity.
+
+## [minProperties/maxProperties are not enforced]
+
+- Status: open
+- Category: correctness
+- Summary: `minProperties`/`maxProperties` constraints are emitted as metadata but never validated.
+- Evidence: `.tmp-workflow-schema-output.ts:2167` (`SwitchItemSchema`), `.tmp-workflow-schema-output.ts:2436` (`TaskListSchema` item), `.tmp-workflow-schema-output.ts:2495` (`ExtensionItemSchema`), `.tmp-workflow-schema-output.ts:260` (`ErrorFilterSchema`), `.tmp-workflow-schema-output.ts:660` (`DurationInline`).
+- Impact: Objects meant to be non-empty or single-key allow invalid shapes.
+- Proposed fix: Add object-level property count validation in `parseObject` (likely via `superRefine`), with awareness of `additionalProperties`, `patternProperties`, and `unevaluatedProperties`.
+- Related: unevaluatedProperties is ignored
+- Depends on: —
+- Notes: None.
+
+## [Required property without schema falls back to z.any]
+
+- Status: open
+- Category: type-safety
+- Summary: Required keys that have no property schema are emitted as `z.any()`.
+- Evidence: `.tmp-workflow-schema-output.ts:152` (`McpClientSchema.version`); schema requires `version` but no definition exists (`test/fixtures/workflow.yaml:606-620`).
+- Impact: Output type is overly permissive and hides schema inconsistencies.
+- Proposed fix: Emit a warning when `required` contains undefined properties; optionally support a strict mode that errors on this.
+- Related: Default openness (fallbacks + passthrough) is not configurable
+- Depends on: —
+- Notes: This is a schema authoring issue, but surfacing it improves trust in generated output.
+
+## [anyOf with empty schema collapses to z.any]
+
+- Status: open
+- Category: type-safety
+- Summary: `anyOf: [<schema>, {}]` becomes `z.union([<schema>, z.any()])`, which is effectively `z.any()`.
+- Evidence: `.tmp-workflow-schema-output.ts:1609` (`EventProperties.data`); source schema uses `{}` in `anyOf` (`test/fixtures/workflow.yaml:1549-1553`).
+- Impact: Types and validation are wider than intended; unions become noisy without adding constraints.
+- Proposed fix: Normalize unions/anyOf to detect empty schemas and collapse explicitly to `z.any()`/`z.unknown()` (or emit a warning).
+- Related: Default openness (fallbacks + passthrough) is not configurable
+- Depends on: —
+- Notes: If `useUnknown` is enabled, prefer `z.unknown()` for better type safety.
+
+## [Default openness (fallbacks + passthrough) is not configurable]
+
+- Status: open
+- Category: ergonomics
+- Summary: Missing schemas and `additionalProperties` defaults result in permissive output, with no opt-in strictness mode.
+- Evidence: `src/utils/anyOrUnknown.ts`, `src/parsers/parseSchema.ts`, `src/parsers/parseObject.ts`.
+- Impact: Users who want strict types/validation must modify schemas rather than toggling a generator option.
+- Proposed fix: Add a strictness option that defaults to `unknown`, enforces `additionalProperties` as strict/strip, and optionally tightens recursive record handling.
+- Related: unevaluatedProperties is ignored; Required property without schema falls back to z.any; anyOf with empty schema collapses to z.any
+- Depends on: —
+- Notes: Keep default behavior spec-correct; make strictness opt-in.
+
+## [additionalProperties forces object typing even when schema is unioned with non-objects]
+
+- Status: open
+- Category: correctness
+- Summary: When `additionalProperties` is set alongside `oneOf/anyOf`, the parser assumes the schema is an object and emits an object intersection, which drops non-object branches.
+- Evidence: `HTTPQuerySchema` in `.tmp-workflow-schema-output.ts:171` is `z.intersection(z.looseObject({}), z.xor([object, runtimeExpression]))` while the source allows a runtime-expression branch (`test/fixtures/workflow.yaml:386-398`).
+- Impact: Legitimate non-object values fail validation and types are too narrow.
+- Proposed fix: When `additionalProperties` exists, only force object typing if the schema is explicitly `type: object`; otherwise keep unions intact and apply `additionalProperties` only to object branches.
+- Related: Default openness (fallbacks + passthrough) is not configurable
+- Depends on: —
+- Notes: This is a correctness bug (not just optimization).
+
+## [Large union splitting to avoid TS7056]
+
+- Status: open
+- Category: performance
+- Summary: Very large unions can trigger TS7056 (“inferred type exceeds maximum length”) when emitting declarations; flattening unions can worsen this by expanding the literal union in `.d.ts`.
+- Evidence: Zod issue https://github.com/colinhacks/zod/issues/1040; multiple reports of TS7056 with big unions in libs that emit declarations.
+- Impact: Builds fail when emitting `.d.ts` for large schemas; forces manual annotations or schema splitting.
+- Proposed fix: Add optional union-splitting options for `anyOf`/`type: []` unions:
+  - `maxUnionSize?: number` (threshold to split).
+  - `unionSplitMode?: "inline" | "named"` (named emits `const UnionPartN = z.union([...])` to let TS refer to `typeof UnionPartN` instead of serializing the full literal union).
+  - `unionSplitStrategy?: "chunk" | "balanced"` (chunk into fixed size or balanced tree).
+  - (Optional) `unionTypeAnnotation?: boolean` to emit `z.ZodUnion<[...]>`/`z.ZodType<...>` annotations on named sub-unions, which further reduces serialization size.
+- Related: String-based optimizations are brittle (need structured IR)
+- Depends on: —
+- Notes: Pure nesting (`z.union([z.union([...]), ...])`) is often insufficient because TS flattens unions during inference; naming sub-unions is the more reliable workaround.
+
+## [String-based optimizations are brittle (need structured IR)]
+
+- Status: open
+- Category: ergonomics
+- Summary: Several optimizations parse emitted expression strings (`z.union(...)`, `z.intersection(...)`) instead of operating on structured data.
+- Evidence: `src/utils/normalizeUnion.ts`, `src/utils/schemaRepresentation.ts`, `src/core/emitZod.ts`.
+- Impact: Output changes can silently disable optimizations; harder to maintain/refactor.
+- Proposed fix: Introduce a structured IR (e.g., `SchemaRepresentation` gains `kind`, `children`, `meta`) and perform normalizations on IR before emitting strings; keep a string emission phase only at the end.
+- Related: Large union splitting to avoid TS7056
+- Depends on: —
+- Notes: This can start with union/intersection nodes before a full rewrite.
+
+## [Recursive unions should be wrapped in z.lazy to preserve inference]
+
+- Status: open
+- Category: type-safety
+- Summary: TypeScript collapses mutually recursive discriminated unions (especially with optional props) to `{}`/`unknown` when the union is emitted directly; we currently only wrap refs in `z.lazy`, not the union expression itself.
+- Evidence: `src/parsers/parseOneOf.ts` and `src/parsers/parseAnyOf.ts` emit unions directly; Zod issue #5309 reproduces unknown inference with recursive discriminated unions + `.optional()`; workflow task lists are recursive unions (see `test/fixtures/workflow.yaml` Task list references).
+- Impact: Nested task configs (`try`, `fork`, `listen`, `foreach`) can degrade to `{}`/`unknown` in `z.infer`, forcing consumer casts even though runtime validation is correct.
+- Proposed fix: Detect when a union schema participates in a recursion cycle (via `cycleComponentByName`/`cycleRefNames` or dependency graph) and emit `z.lazy(() => z.discriminatedUnion(...))` / `z.lazy(() => z.union([...]))` with `z.ZodLazy<...>` typing; leave non-recursive unions unchanged.
+- Related: Large union splitting to avoid TS7056; Optional explicit type alias emission for recursive schemas
+- Depends on: —
+- Notes: Zod issue #5309 reports explicit getter annotations are insufficient; union-level `z.lazy` is the most reliable workaround today.
+
+## [Optional explicit type alias emission for recursive schemas]
+
+- Status: open
+- Category: type-safety
+- Summary: Even with lazy/getter patterns, TypeScript can infer `{}`/`unknown` for recursive schemas; emitting explicit TS type aliases (or annotating lazies with `z.ZodType<Foo>`) can stabilize inference for consumers.
+- Evidence: `src/core/emitZod.ts` only emits Zod schema consts; no `type Foo = z.output<typeof FooSchema>` is generated; workflow recursion paths require runtime interfaces today (see `test/fixtures/workflow.yaml` task list recursion).
+- Impact: Consumers must hand-write runtime interfaces or `as` assertions for recursive fields; type safety depends on user code rather than the generator.
+- Proposed fix: Add an opt-in `emitTypeAliases`/`typeExports` mode to export `type Foo = z.output<typeof FooSchema>` (or schema-derived TS types) and optionally annotate lazies as `z.ZodType<Foo>` to preserve inference across cycles.
+- Related: Recursive unions should be wrapped in z.lazy to preserve inference
+- Depends on: —
+- Notes: Keep default output unchanged; opt-in to avoid larger bundle size and to allow staged adoption.

package/package.json

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