@gabrielbryk/json-schema-to-zod 2.12.0 → 2.13.0

package/dist/parsers/parseOneOf.js

@@ -1,6 +1,5 @@
 import { parseSchema } from "./parseSchema.js";
 import { anyOrUnknown } from "../utils/anyOrUnknown.js";
-import { extractInlineObject } from "../utils/extractInlineObject.js";
 import { resolveRef } from "../utils/resolveRef.js";
 /**
  * Check if a schema is a "required-only" validation constraint.
@@ -32,9 +31,6 @@ const isRequiredOnlySchema = (schema) => {
 /**
  * Generate a superRefine expression that validates required field combinations.
  * This handles the JSON Schema pattern where oneOf is used purely for validation.
- *
- * When isRefinementOnly is true, the expression is just the refinement function body
- * that should be appended with .superRefine() directly to the parent schema.
  */
 const generateRequiredFieldsRefinement = (requiredCombinations) => {
     const conditions = requiredCombinations.map((fields) => {
@@ -71,13 +67,13 @@ const collectSchemaProperties = (schema, refs) => {
     // Collect from allOf members
     if (Array.isArray(schema.allOf)) {
         for (const member of schema.allOf) {
-            if (typeof member !== 'object' || member === null)
+            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) {
+                if (resolved && typeof resolved.schema === "object" && resolved.schema !== null) {
                     resolvedMember = resolved.schema;
                 }
                 else {
@@ -113,18 +109,18 @@ const setsEqual = (a, b) => {
     return true;
 };
 /**
- * Extract the constant value from a property schema.
- * Returns the string value if it's a const or single-element enum, undefined otherwise.
+ * Extract discriminator values from a property schema.
+ * Returns string values if it's a const or enum, undefined otherwise.
  */
-const getConstValue = (prop) => {
-    if (prop.const !== undefined && typeof prop.const === 'string') {
-        return prop.const;
+const getDiscriminatorValues = (prop) => {
+    if (prop.const !== undefined && typeof prop.const === "string") {
+        return [prop.const];
     }
     if (prop.enum &&
         Array.isArray(prop.enum) &&
-        prop.enum.length === 1 &&
-        typeof prop.enum[0] === 'string') {
-        return prop.enum[0];
+        prop.enum.length > 0 &&
+        prop.enum.every((value) => typeof value === "string")) {
+        return prop.enum;
     }
     return undefined;
 };
@@ -134,22 +130,16 @@ const getConstValue = (prop) => {
  */
 const getNegatedEnumValues = (prop) => {
     if (prop.not &&
-        typeof prop.not === 'object' &&
+        typeof prop.not === "object" &&
         prop.not !== null &&
         Array.isArray(prop.not.enum) &&
-        prop.not.enum.every((v) => typeof v === 'string')) {
+        prop.not.enum.every((v) => typeof v === "string")) {
         return prop.not.enum;
     }
     return undefined;
 };
 /**
  * Attempts to find a discriminator property common to all options.
- * A discriminator must:
- * 1. Be present in 'properties' of all options (resolving $refs and allOf if needed)
- * 2. Be required in all options (checking both direct required and allOf required)
- * 3. Have a constant string value (const or enum: [val]) in all options, OR
- *    have constant values in all but one option which has not:{enum:[those values]}
- * 4. Have unique values across all options (for const values)
  */
 const findImplicitDiscriminator = (options, refs) => {
     if (options.length < 2)
@@ -157,13 +147,13 @@ const findImplicitDiscriminator = (options, refs) => {
     // Fully resolve schemas and collect their properties (including from allOf)
     const resolvedOptions = [];
     for (const opt of options) {
-        if (typeof opt !== 'object' || opt === null)
+        if (typeof opt !== "object" || opt === null)
             return undefined;
         let schemaObj = opt;
         // Resolve ref if needed
         if (schemaObj.$ref || schemaObj.$dynamicRef) {
             const resolved = resolveRef(schemaObj, (schemaObj.$ref || schemaObj.$dynamicRef), refs);
-            if (resolved && typeof resolved.schema === 'object' && resolved.schema !== null) {
+            if (resolved && typeof resolved.schema === "object" && resolved.schema !== null) {
                 schemaObj = resolved.schema;
             }
             else {
@@ -171,7 +161,7 @@ const findImplicitDiscriminator = (options, refs) => {
             }
         }
         // Must be an object type
-        if (schemaObj.type !== 'object') {
+        if (schemaObj.type !== "object") {
             return undefined;
         }
         // Collect all properties including from allOf
@@ -190,6 +180,7 @@ const findImplicitDiscriminator = (options, refs) => {
         let defaultIndex;
         let defaultEnumValues;
         let isValidDiscriminator = true;
+        let optionsWithDiscriminator = 0;
         for (let i = 0; i < resolvedOptions.length; i++) {
             const opt = resolvedOptions[i];
             // Must be required
@@ -204,25 +195,31 @@ const findImplicitDiscriminator = (options, refs) => {
             }
             // Resolve property schema ref if needed (e.g. definitions/kind -> const)
             let prop = propBeforeResolve;
-            if (typeof prop === 'object' && prop !== null && (prop.$ref || prop.$dynamicRef)) {
+            if (typeof prop === "object" && prop !== null && (prop.$ref || prop.$dynamicRef)) {
                 const resolvedProp = resolveRef(prop, (prop.$ref || prop.$dynamicRef), refs);
                 if (resolvedProp) {
                     prop = resolvedProp.schema;
                 }
             }
-            if (typeof prop !== 'object' || prop === null) {
+            if (typeof prop !== "object" || prop === null) {
                 isValidDiscriminator = false;
                 break;
             }
             // Check for constant value
-            const constValue = getConstValue(prop);
+            const constValue = getDiscriminatorValues(prop);
             if (constValue !== undefined) {
-                if (constValuesSet.has(constValue)) {
-                    isValidDiscriminator = false; // Duplicate value found
+                optionsWithDiscriminator += 1;
+                for (const value of constValue) {
+                    if (constValuesSet.has(value)) {
+                        isValidDiscriminator = false; // Duplicate value found
+                        break;
+                    }
+                    constValuesSet.add(value);
+                    constValues.push(value);
+                }
+                if (!isValidDiscriminator) {
                     break;
                 }
-                constValuesSet.add(constValue);
-                constValues.push(constValue);
                 continue;
             }
             // Check for negated enum (default case pattern)
@@ -245,17 +242,17 @@ const findImplicitDiscriminator = (options, refs) => {
             continue;
         }
         // Check if all options have const values (full discriminated union)
-        if (constValues.length === resolvedOptions.length) {
-            return { type: 'full', key };
+        if (optionsWithDiscriminator === resolvedOptions.length) {
+            return { type: "full", key };
         }
         // Check if we have a valid default case pattern
         if (defaultIndex !== undefined &&
             defaultEnumValues !== undefined &&
-            constValues.length === resolvedOptions.length - 1) {
+            optionsWithDiscriminator === resolvedOptions.length - 1) {
             // Verify the negated enum exactly matches the const values
             const enumSet = new Set(defaultEnumValues);
             if (setsEqual(constValuesSet, enumSet)) {
-                return { type: 'withDefault', key, defaultIndex, constValues };
+                return { type: "withDefault", key, defaultIndex, constValues };
             }
         }
     }
@@ -279,87 +276,47 @@ export const parseOneOf = (schema, refs) => {
     }
     // Optimize: Check for implicit discriminated union
     const discriminator = findImplicitDiscriminator(schema.oneOf, refs);
-    if (discriminator?.type === 'full') {
+    if (discriminator?.type === "full") {
         // All options have constant discriminator values
         const options = schema.oneOf.map((s, i) => parseSchema(s, {
             ...refs,
             path: [...refs.path, "oneOf", i],
         }));
-        const expressions = options.map(o => o.expression).join(", ");
-        const types = options.map(o => o.type).join(", ");
+        const expressions = options.map((o) => o.expression).join(", ");
+        const types = options.map((o) => o.type).join(", ");
         return {
             expression: `z.discriminatedUnion("${discriminator.key}", [${expressions}])`,
             // Use readonly tuple for union type annotations (required for recursive type inference)
             type: `z.ZodDiscriminatedUnion<"${discriminator.key}", readonly [${types}]>`,
         };
     }
-    // Note: 'withDefault' case (discriminated union with catch-all) cannot be optimized
-    // in Zod v4 because ZodDiscriminatedUnion cannot be nested inside ZodUnion at the type level.
-    // The runtime would work, but the types wouldn't match, causing compile errors.
-    // So we fall through to the regular union handling below.
-    // Fallback: Standard z.union
+    // Fallback: Use z.xor for exclusive unions
+    // z.xor takes exactly two arguments.
+    // If more than 2, we must nest them: z.xor(A, z.xor(B, C)) ?
+    // Or usage says: export function xor<const T extends readonly core.SomeType[]>(options: T, ...): ZodXor<T>
+    // Wait, let's check `schemas.ts` again.
+    // export function xor<const T extends readonly core.SomeType[]>(options: T, params?: ...): ZodXor<T>
+    // It takes an array of options!
+    // Wait, in `from-json-schema.ts` (Zod repo), how is it used?
+    // It uses `z.xor`.
+    // Let's verify `schemas.ts` content I viewed earlier.
+    // Line 1368: export function xor<const T extends readonly core.SomeType[]>(options: T, params?: ...): ZodXor<T>
+    // Yes, it takes an array `options`.
+    // It says "Unlike regular unions that succeed when any option matches, xor fails if zero or more than one option matches the input."
+    // Perfect.
     const parsedSchemas = schema.oneOf.map((s, i) => {
-        const extracted = extractInlineObject(s, refs, [...refs.path, "oneOf", i]);
-        if (extracted) {
-            // extractInlineObject returns a refName string
-            return { expression: extracted, type: `typeof ${extracted}` };
-        }
-        let parsed = parseSchema(s, {
+        const parsed = parseSchema(s, {
             ...refs,
             path: [...refs.path, "oneOf", i],
         });
-        // Make regular unions stricter: if it's an object, it shouldn't match emptiness.
-        // Ensure we only apply .strict() to actual z.object() calls.
-        if (typeof s === "object" &&
-            s !== null &&
-            (s.type === "object" || s.properties) &&
-            !s.$ref &&
-            parsed.expression.startsWith("z.object(") && // Critical check: Must be a Zod object
-            !parsed.expression.includes(".and(") &&
-            !parsed.expression.includes(".intersection(") &&
-            !parsed.expression.includes(".strict()") &&
-            !parsed.expression.includes(".catchall") &&
-            !parsed.expression.includes(".passthrough")) {
-            parsed = {
-                expression: parsed.expression + ".strict()",
-                type: parsed.type, // .strict() doesn't change the Zod type
-            };
-        }
         return parsed;
     });
-    // Build the union types for the SchemaRepresentation
-    const unionTypes = parsedSchemas.map(r => r.type).join(", ");
-    const unionExpression = `z.union([${parsedSchemas.map(r => r.expression).join(", ")}])`;
-    if (refs.strictOneOf) {
-        const schemasExpressions = parsedSchemas.map(r => r.expression).join(", ");
-        const expression = `${unionExpression}.superRefine((x, ctx) => {
-    const schemas = [${schemasExpressions}];
-    const errors = schemas.reduce<z.ZodError[]>(
-      (errors, schema) =>
-        ((result) =>
-          result.error ? [...errors, result.error] : errors)(
-          schema.safeParse(x),
-        ),
-      [],
-    );
-    if (schemas.length - errors.length !== 1) {
-      ctx.addIssue({
-        path: [],
-        code: "invalid_union",
-        errors: errors.map(e => e.issues),
-        message: "Invalid input: Should pass single schema",
-      });
-    }
-  })`;
-        return {
-            expression,
-            // In Zod v4, .superRefine() doesn't change the type
-            type: `z.ZodUnion<readonly [${unionTypes}]>`,
-        };
-    }
+    const expressions = parsedSchemas.map((r) => r.expression).join(", ");
+    const types = parsedSchemas.map((r) => r.type).join(", ");
+    const expression = `z.xor([${expressions}])`;
+    const type = `z.ZodXor<readonly [${types}]>`;
     return {
-        expression: unionExpression,
-        // Use readonly tuple for union type annotations (required for recursive type inference)
-        type: `z.ZodUnion<readonly [${unionTypes}]>`,
+        expression,
+        type,
     };
 };

package/dist/parsers/parseSchema.js

@@ -28,9 +28,7 @@ export const parseSchema = (schema, refs = { seen: new Map(), path: [] }, blockM
     refs.refNameByPointer = refs.refNameByPointer ?? new Map();
     refs.usedNames = refs.usedNames ?? new Set();
     if (typeof schema !== "object") {
-        return schema
-            ? anyOrUnknown(refs)
-            : { expression: "z.never()", type: "z.ZodNever" };
+        return schema ? anyOrUnknown(refs) : { expression: "z.never()", type: "z.ZodNever" };
     }
     const parentBase = refs.currentBaseUri ?? refs.rootBaseUri ?? "root:///";
     const baseUri = typeof schema.$id === "string" ? resolveUri(parentBase, schema.$id) : parentBase;
@@ -43,7 +41,11 @@ export const parseSchema = (schema, refs = { seen: new Map(), path: [] }, blockM
         });
     }
     if (refs.parserOverride) {
-        const custom = refs.parserOverride(schema, { ...refs, currentBaseUri: baseUri, dynamicAnchors });
+        const custom = refs.parserOverride(schema, {
+            ...refs,
+            currentBaseUri: baseUri,
+            dynamicAnchors,
+        });
         if (typeof custom === "string") {
             // ParserOverride returns string for backward compatibility
             return { expression: custom, type: "z.ZodTypeAny" };
@@ -71,7 +73,7 @@ export const parseSchema = (schema, refs = { seen: new Map(), path: [] }, blockM
     let parsed = selectParser(schema, { ...refs, currentBaseUri: baseUri, dynamicAnchors });
     if (!blockMeta) {
         if (!refs.withoutDescribes) {
-            parsed = addDescribes(schema, parsed, { ...refs, currentBaseUri: baseUri, dynamicAnchors });
+            parsed = addDescribes(schema, parsed);
         }
         if (!refs.withoutDefaults) {
             parsed = addDefaults(schema, parsed);
@@ -123,60 +125,128 @@ 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);
-    const refType = `typeof ${refName}`;
-    // For same-cycle refs, check if we need special handling
-    if (isSameCycle || isForwardRef) {
-        // Check context: are we inside an object property where getters work?
-        // IMPORTANT: additionalProperties becomes z.record() which does NOT support getters
-        // Only named properties (properties, patternProperties) can use getters
-        const inNamedProperty = refs.path.includes("properties") ||
-            refs.path.includes("patternProperties");
-        // additionalProperties becomes z.record() value - getters don't work there
-        // Per Zod issue #4881: z.record() with recursive values REQUIRES z.lazy()
-        const inRecordContext = refs.path.includes("additionalProperties");
-        // Self-recursion in named object properties: use direct ref (getter handles deferred eval)
-        const isSelfRecursion = refName === refs.currentSchemaName;
-        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 };
-        }
-        // 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()
-        if (isForwardRef || inRecordContext) {
-            return {
-                expression: `z.lazy(() => ${refName})`,
-                type: `z.ZodLazy<${refType}>`
-            };
-        }
+    // 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
+    // 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}`;
+    // 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}>`,
+        };
     }
     return { expression: refName, type: refType };
 };
-const addDescribes = (schema, parsed, refs) => {
+const addDescribes = (schema, parsed) => {
     let { expression, type } = parsed;
-    // Use .meta() for richer metadata when withMeta is enabled
-    if (refs?.withMeta) {
-        const meta = {};
-        if (schema.$id)
-            meta.id = schema.$id;
-        if (schema.title)
-            meta.title = schema.title;
-        if (schema.description)
-            meta.description = schema.description;
-        if (schema.examples)
-            meta.examples = schema.examples;
-        if (schema.deprecated)
-            meta.deprecated = schema.deprecated;
+    const meta = {};
+    if (schema.$id)
+        meta.id = schema.$id;
+    if (schema.title)
+        meta.title = schema.title;
+    if (schema.description)
+        meta.description = schema.description;
+    if (schema.examples)
+        meta.examples = schema.examples;
+    if (schema.deprecated)
+        meta.deprecated = schema.deprecated;
+    // Collect other unknown keywords as metadata if configured
+    // This aligns with Zod v4 "Custom metadata is preserved"
+    // We can filter out known keywords to find the "unknown" ones.
+    // This list needs to be comprehensive to avoid polluting meta with standard logic keywords.
+    const knownKeywords = new Set([
+        "type",
+        "properties",
+        "additionalProperties",
+        "patternProperties",
+        "items",
+        "prefixItems",
+        "additionalItems",
+        "contains",
+        "minContains",
+        "maxContains",
+        "required",
+        "enum",
+        "const",
+        "format",
+        "minLength",
+        "maxLength",
+        "pattern",
+        "minimum",
+        "maximum",
+        "exclusiveMinimum",
+        "exclusiveMaximum",
+        "multipleOf",
+        "if",
+        "then",
+        "else",
+        "allOf",
+        "anyOf",
+        "oneOf",
+        "not",
+        "$id",
+        "$ref",
+        "$dynamicRef",
+        "$dynamicAnchor",
+        "$schema",
+        "$defs",
+        "definitions",
+        "title",
+        "description",
+        "default",
+        "examples",
+        "deprecated",
+        "readOnly",
+        "writeOnly",
+        "contentEncoding",
+        "contentMediaType",
+        "contentSchema",
+        "dependentRequired",
+        "dependentSchemas",
+        "propertyNames",
+        "unevaluatedProperties",
+        "unevaluatedItems",
+        "nullable",
+        "discriminator",
+        "errorMessage",
+        "externalDocs",
+        "__originalIndex",
+    ]);
+    Object.keys(schema).forEach((key) => {
+        if (!knownKeywords.has(key)) {
+            meta[key] = schema[key];
+        }
+    });
+    if (Object.keys(meta).length > 0) {
+        // Only add .meta() if there is something to add
+        // Note: Zod v4 .describe() writes to description too, which meta does too?
+        // Zod .describe() sets the description property of the schema def.
+        // .meta() is for custom metadata.
+        // If strict on description, use .describe().
+        // Zod v4: schema.describe("foo") sets description.
+        // schema.meta({ ... }) is for other stuff?
+        // Actually, Zod documentation says: "Custom metadata is preserved".
+        if (meta.description) {
+            expression += `.describe(${JSON.stringify(meta.description)})`;
+            delete meta.description; // Don't duplicate in meta object if using describe
+        }
         if (Object.keys(meta).length > 0) {
             expression += `.meta(${JSON.stringify(meta)})`;
         }
     }
-    else if (schema.description) {
-        expression += `.describe(${JSON.stringify(schema.description)})`;
-    }
     return { expression, type };
 };
 const getOrCreateRefName = (pointer, path, refs) => {
@@ -214,7 +284,11 @@ const buildNameFromPath = (path, used) => {
                 .join(""))
             .join("")
         : "Ref";
-    const sanitized = sanitizeIdentifier(base || "Ref");
+    let finalName = base;
+    if (!finalName.endsWith("Schema")) {
+        finalName += "Schema";
+    }
+    const sanitized = sanitizeIdentifier(finalName);
     if (!used || !used.has(sanitized))
         return sanitized;
     let counter = 2;
@@ -283,8 +357,7 @@ const selectParser = (schema, refs) => {
     else if (its.a.primitive(schema, "string")) {
         return parseString(schema, refs);
     }
-    else if (its.a.primitive(schema, "number") ||
-        its.a.primitive(schema, "integer")) {
+    else if (its.a.primitive(schema, "number") || its.a.primitive(schema, "integer")) {
         return parseNumber(schema);
     }
     else if (its.a.primitive(schema, "boolean")) {
@@ -302,7 +375,11 @@ const selectParser = (schema, refs) => {
 };
 export const its = {
     an: {
-        object: (x) => x.type === "object",
+        object: (x) => x.type === "object" ||
+            x.properties !== undefined ||
+            x.additionalProperties !== undefined ||
+            x.patternProperties !== undefined ||
+            x.required !== undefined,
         array: (x) => x.type === "array",
         anyOf: (x) => x.anyOf !== undefined,
         allOf: (x) => x.allOf !== undefined,

package/dist/parsers/parseSimpleDiscriminatedOneOf.js

@@ -15,8 +15,8 @@ export const parseSimpleDiscriminatedOneOf = (schema, refs) => {
             path: [...refs.path, "oneOf", 0],
         });
     }
-    const expressions = options.map(o => o.expression).join(", ");
-    const types = options.map(o => o.type).join(", ");
+    const expressions = options.map((o) => o.expression).join(", ");
+    const types = options.map((o) => o.type).join(", ");
     return {
         expression: `z.discriminatedUnion("${discriminator}", [${expressions}])`,
         type: `z.ZodDiscriminatedUnion<"${discriminator}", [${types}]>`,