zod 3.26.0-canary.20250703T215303 → 3.26.0-canary.20250708T090717

package/v4/core/schemas.d.ts

@@ -32,7 +32,6 @@ export interface _$ZodTypeInternals {
     /** Schema definition. */
     def: $ZodTypeDef;
     /** @internal Randomly generated ID for this schema. */
-    id: string;
     /** @internal List of deferred initializers. */
     deferred: util.AnyFunc[] | undefined;
     /** @internal Parses input and runs all checks (refinements). */
@@ -516,11 +515,13 @@ export interface $ZodArrayDef<T extends SomeType = $ZodType> extends $ZodTypeDef
     type: "array";
     element: T;
 }
-export interface $ZodArrayInternals<T extends SomeType = $ZodType> extends $ZodTypeInternals<core.output<T>[], core.input<T>[]> {
+export interface $ZodArrayInternals<T extends SomeType = $ZodType> extends _$ZodTypeInternals {
     def: $ZodArrayDef<T>;
     isst: errors.$ZodIssueInvalidType;
+    output: core.output<T>[];
+    input: core.input<T>[];
 }
-export interface $ZodArray<T extends SomeType = $ZodType> extends $ZodType<core.output<T>[], core.input<T>[], $ZodArrayInternals<T>> {
+export interface $ZodArray<T extends SomeType = $ZodType> extends $ZodType<any, any, $ZodArrayInternals<T>> {
 }
 export declare const $ZodArray: core.$constructor<$ZodArray>;
 type OptionalOutSchema = {
@@ -533,12 +534,12 @@ type OptionalInSchema = {
         optin: "optional";
     };
 };
-export type $InferObjectOutput<T extends $ZodLooseShape, Extra extends Record<string, unknown>> = string extends keyof T ? Record<string, unknown> : keyof (T & Extra) extends never ? Record<string, never> : util.Prettify<{
+export type $InferObjectOutput<T extends $ZodLooseShape, Extra extends Record<string, unknown>> = string extends keyof T ? util.IsAny<T[keyof T]> extends true ? Record<string, unknown> : Record<string, core.output<T[keyof T]>> : keyof (T & Extra) extends never ? Record<string, never> : util.Prettify<{
     -readonly [k in keyof T as T[k] extends OptionalOutSchema ? never : k]: T[k]["_zod"]["output"];
 } & {
     -readonly [k in keyof T as T[k] extends OptionalOutSchema ? k : never]?: T[k]["_zod"]["output"];
 } & Extra>;
-export type $InferObjectInput<T extends $ZodLooseShape, Extra extends Record<string, unknown>> = string extends keyof T ? Record<string, unknown> : keyof (T & Extra) extends never ? Record<string, never> : util.Prettify<{
+export type $InferObjectInput<T extends $ZodLooseShape, Extra extends Record<string, unknown>> = string extends keyof T ? util.IsAny<T[keyof T]> extends true ? Record<string, unknown> : Record<string, core.input<T[keyof T]>> : keyof (T & Extra) extends never ? Record<string, never> : util.Prettify<{
     -readonly [k in keyof T as T[k] extends OptionalInSchema ? never : k]: T[k]["_zod"]["input"];
 } & {
     -readonly [k in keyof T as T[k] extends OptionalInSchema ? k : never]?: T[k]["_zod"]["input"];
@@ -600,14 +601,17 @@ export interface $ZodUnionDef<Options extends readonly SomeType[] = readonly $Zo
 }
 type IsOptionalIn<T extends SomeType> = T extends OptionalInSchema ? true : false;
 type IsOptionalOut<T extends SomeType> = T extends OptionalOutSchema ? true : false;
-export interface $ZodUnionInternals<T extends readonly SomeType[] = readonly $ZodType[]> extends $ZodTypeInternals<$InferUnionOutput<T[number]>, $InferUnionInput<T[number]>> {
+export interface $ZodUnionInternals<T extends readonly SomeType[] = readonly $ZodType[]> extends _$ZodTypeInternals {
     def: $ZodUnionDef<T>;
     isst: errors.$ZodIssueInvalidUnion;
     pattern: T[number]["_zod"]["pattern"];
+    values: T[number]["_zod"]["values"];
+    output: $InferUnionOutput<T[number]>;
+    input: $InferUnionInput<T[number]>;
     optin: IsOptionalIn<T[number]> extends false ? "optional" | undefined : "optional";
     optout: IsOptionalOut<T[number]> extends false ? "optional" | undefined : "optional";
 }
-export interface $ZodUnion<T extends readonly SomeType[] = readonly $ZodType[]> extends $ZodType {
+export interface $ZodUnion<T extends readonly SomeType[] = readonly $ZodType[]> extends $ZodType<any, any, $ZodUnionInternals<T>> {
     _zod: $ZodUnionInternals<T>;
 }
 export declare const $ZodUnion: core.$constructor<$ZodUnion>;
@@ -631,6 +635,8 @@ export interface $ZodIntersectionDef<Left extends SomeType = $ZodType, Right ext
 export interface $ZodIntersectionInternals<A extends SomeType = $ZodType, B extends SomeType = $ZodType> extends $ZodTypeInternals<core.output<A> & core.output<B>, core.input<A> & core.input<B>> {
     def: $ZodIntersectionDef<A, B>;
     isst: never;
+    optin: A["_zod"]["optin"] | B["_zod"]["optin"];
+    optout: A["_zod"]["optout"] | B["_zod"]["optout"];
 }
 export interface $ZodIntersection<A extends SomeType = $ZodType, B extends SomeType = $ZodType> extends $ZodType {
     _zod: $ZodIntersectionInternals<A, B>;
@@ -677,12 +683,17 @@ export interface $ZodRecordDef<Key extends $ZodRecordKey = $ZodRecordKey, Value
     keyType: Key;
     valueType: Value;
 }
-export type $InferZodRecordOutput<Key extends $ZodRecordKey = $ZodRecordKey, Value extends SomeType = $ZodType> = undefined extends Key["_zod"]["values"] ? string extends core.output<Key> ? Record<core.output<Key>, core.output<Value>> : number extends core.output<Key> ? Record<core.output<Key>, core.output<Value>> : symbol extends core.output<Key> ? Record<core.output<Key>, core.output<Value>> : Partial<Record<core.output<Key>, core.output<Value>>> : Record<core.output<Key>, core.output<Value>>;
-export type $InferZodRecordInput<Key extends $ZodRecordKey = $ZodRecordKey, Value extends SomeType = $ZodType> = undefined extends Key["_zod"]["values"] ? string extends core.input<Key> ? Record<core.input<Key>, core.input<Value>> : number extends core.input<Key> ? Record<core.input<Key>, core.input<Value>> : symbol extends core.input<Key> ? Record<core.input<Key>, core.input<Value>> : Partial<Record<core.input<Key>, core.input<Value>>> : Record<core.input<Key>, core.input<Value>>;
+export type $InferZodRecordOutput<Key extends $ZodRecordKey = $ZodRecordKey, Value extends SomeType = $ZodType> = Key extends $partial ? Partial<Record<core.output<Key>, core.output<Value>>> : Record<core.output<Key>, core.output<Value>>;
+export type $InferZodRecordInput<Key extends $ZodRecordKey = $ZodRecordKey, Value extends SomeType = $ZodType> = Key extends $partial ? Partial<Record<core.input<Key>, core.input<Value>>> : Record<core.input<Key>, core.input<Value>>;
 export interface $ZodRecordInternals<Key extends $ZodRecordKey = $ZodRecordKey, Value extends SomeType = $ZodType> extends $ZodTypeInternals<$InferZodRecordOutput<Key, Value>, $InferZodRecordInput<Key, Value>> {
     def: $ZodRecordDef<Key, Value>;
     isst: errors.$ZodIssueInvalidType | errors.$ZodIssueInvalidKey<Record<PropertyKey, unknown>>;
+    optin?: "optional" | undefined;
+    optout?: "optional" | undefined;
 }
+export type $partial = {
+    "~~partial": true;
+};
 export interface $ZodRecord<Key extends $ZodRecordKey = $ZodRecordKey, Value extends SomeType = $ZodType> extends $ZodType {
     _zod: $ZodRecordInternals<Key, Value>;
 }
@@ -695,6 +706,8 @@ export interface $ZodMapDef<Key extends SomeType = $ZodType, Value extends SomeT
 export interface $ZodMapInternals<Key extends SomeType = $ZodType, Value extends SomeType = $ZodType> extends $ZodTypeInternals<Map<core.output<Key>, core.output<Value>>, Map<core.input<Key>, core.input<Value>>> {
     def: $ZodMapDef<Key, Value>;
     isst: errors.$ZodIssueInvalidType | errors.$ZodIssueInvalidKey | errors.$ZodIssueInvalidElement<unknown>;
+    optin?: "optional" | undefined;
+    optout?: "optional" | undefined;
 }
 export interface $ZodMap<Key extends SomeType = $ZodType, Value extends SomeType = $ZodType> extends $ZodType {
     _zod: $ZodMapInternals<Key, Value>;
@@ -707,6 +720,8 @@ export interface $ZodSetDef<T extends SomeType = $ZodType> extends $ZodTypeDef {
 export interface $ZodSetInternals<T extends SomeType = $ZodType> extends $ZodTypeInternals<Set<core.output<T>>, Set<core.input<T>>> {
     def: $ZodSetDef<T>;
     isst: errors.$ZodIssueInvalidType;
+    optin?: "optional" | undefined;
+    optout?: "optional" | undefined;
 }
 export interface $ZodSet<T extends SomeType = $ZodType> extends $ZodType {
     _zod: $ZodSetInternals<T>;
@@ -819,6 +834,7 @@ export interface $ZodDefaultDef<T extends SomeType = $ZodType> extends $ZodTypeD
 export interface $ZodDefaultInternals<T extends SomeType = $ZodType> extends $ZodTypeInternals<util.NoUndefined<core.output<T>>, core.input<T> | undefined> {
     def: $ZodDefaultDef<T>;
     optin: "optional";
+    optout?: "optional" | undefined;
     isst: never;
     values: T["_zod"]["values"];
 }
@@ -835,6 +851,7 @@ export interface $ZodPrefaultDef<T extends SomeType = $ZodType> extends $ZodType
 export interface $ZodPrefaultInternals<T extends SomeType = $ZodType> extends $ZodTypeInternals<util.NoUndefined<core.output<T>>, core.input<T> | undefined> {
     def: $ZodPrefaultDef<T>;
     optin: "optional";
+    optout?: "optional" | undefined;
     isst: never;
     values: T["_zod"]["values"];
 }
@@ -850,6 +867,8 @@ export interface $ZodNonOptionalInternals<T extends SomeType = $ZodType> extends
     def: $ZodNonOptionalDef<T>;
     isst: errors.$ZodIssueInvalidType;
     values: T["_zod"]["values"];
+    optin: "optional" | undefined;
+    optout: "optional" | undefined;
 }
 export interface $ZodNonOptional<T extends SomeType = $ZodType> extends $ZodType {
     _zod: $ZodNonOptionalInternals<T>;
@@ -862,6 +881,8 @@ export interface $ZodSuccessDef<T extends SomeType = $ZodType> extends $ZodTypeD
 export interface $ZodSuccessInternals<T extends SomeType = $ZodType> extends $ZodTypeInternals<boolean, core.input<T>> {
     def: $ZodSuccessDef<T>;
     isst: never;
+    optin: T["_zod"]["optin"];
+    optout: "optional" | undefined;
 }
 export interface $ZodSuccess<T extends SomeType = $ZodType> extends $ZodType {
     _zod: $ZodSuccessInternals<T>;
@@ -928,6 +949,7 @@ export interface $ZodReadonlyInternals<T extends SomeType = $ZodType> extends $Z
     optout: T["_zod"]["optout"];
     isst: never;
     propValues: T["_zod"]["propValues"];
+    values: T["_zod"]["values"];
 }
 export interface $ZodReadonly<T extends SomeType = $ZodType> extends $ZodType {
     _zod: $ZodReadonlyInternals<T>;

package/v4/core/schemas.js

@@ -8,8 +8,6 @@ import { version } from "./versions.js";
 export const $ZodType = /*@__PURE__*/ core.$constructor("$ZodType", (inst, def) => {
     var _a;
     inst ?? (inst = {});
-    // avoids issues with using Math.random() in Next.js caching
-    util.defineLazy(inst._zod, "id", () => def.type + "_" + util.randomString(10));
     inst._zod.def = def; // set _def property
     inst._zod.bag = inst._zod.bag || {}; // initialize _bag object
     inst._zod.version = version;
@@ -37,8 +35,8 @@ export const $ZodType = /*@__PURE__*/ core.$constructor("$ZodType", (inst, def)
             let isAborted = util.aborted(payload);
             let asyncResult;
             for (const ch of checks) {
-                if (ch._zod.when) {
-                    const shouldRun = ch._zod.when(payload);
+                if (ch._zod.def.when) {
+                    const shouldRun = ch._zod.def.when(payload);
                     if (!shouldRun)
                         continue;
                 }
@@ -158,7 +156,9 @@ export const $ZodURL = /*@__PURE__*/ core.$constructor("$ZodURL", (inst, def) =>
     $ZodStringFormat.init(inst, def);
     inst._zod.check = (payload) => {
         try {
-            const url = new URL(payload.value);
+            const orig = payload.value;
+            const url = new URL(orig);
+            const href = url.href;
             if (def.hostname) {
                 def.hostname.lastIndex = 0;
                 if (!def.hostname.test(url.hostname)) {
@@ -187,6 +187,13 @@ export const $ZodURL = /*@__PURE__*/ core.$constructor("$ZodURL", (inst, def) =>
                     });
                 }
             }
+            // payload.value = url.href;
+            if (!orig.endsWith("/") && href.endsWith("/")) {
+                payload.value = href.slice(0, -1);
+            }
+            else {
+                payload.value = href;
+            }
             return;
         }
         catch (_) {
@@ -720,8 +727,9 @@ export const $ZodObject = /*@__PURE__*/ core.$constructor("$ZodObject", (inst, d
         };
         doc.write(`const input = payload.value;`);
         const ids = Object.create(null);
+        let counter = 0;
         for (const key of normalized.keys) {
-            ids[key] = util.randomString(15);
+            ids[key] = `key_${counter++}`;
         }
         // A: preserve key order {
         doc.write(`const newResult = {}`);
@@ -1595,6 +1603,7 @@ function handlePipeResult(left, def, ctx) {
 export const $ZodReadonly = /*@__PURE__*/ core.$constructor("$ZodReadonly", (inst, def) => {
     $ZodType.init(inst, def);
     util.defineLazy(inst._zod, "propValues", () => def.innerType._zod.propValues);
+    util.defineLazy(inst._zod, "values", () => def.innerType._zod.values);
     util.defineLazy(inst._zod, "optin", () => def.innerType._zod.optin);
     util.defineLazy(inst._zod, "optout", () => def.innerType._zod.optout);
     inst._zod.parse = (payload, ctx) => {

package/v4/core/to-json-schema.cjs

@@ -36,7 +36,7 @@ class JSONSchemaGenerator {
             return seen.schema;
         }
         // initialize
-        const result = { schema: {}, count: 1, cycle: undefined };
+        const result = { schema: {}, count: 1, cycle: undefined, path: _params.path };
         this.seen.set(schema, result);
         // custom method overrides default behavior
         const overrideSchema = schema._zod.toJSONSchema?.();
@@ -151,9 +151,10 @@ class JSONSchemaGenerator {
                     case "unknown": {
                         break;
                     }
-                    case "undefined":
-                    case "never": {
-                        _json.not = {};
+                    case "undefined": {
+                        if (this.unrepresentable === "throw") {
+                            throw new Error("Undefined cannot be represented in JSON Schema");
+                        }
                         break;
                     }
                     case "void": {
@@ -162,6 +163,10 @@ class JSONSchemaGenerator {
                         }
                         break;
                     }
+                    case "never": {
+                        _json.not = {};
+                        break;
+                    }
                     case "date": {
                         if (this.unrepresentable === "throw") {
                             throw new Error("Date cannot be represented in JSON Schema");
@@ -531,6 +536,8 @@ class JSONSchemaGenerator {
             throw new Error("Unprocessed schema. This is a bug in Zod.");
         // initialize result with root schema fields
         // Object.assign(result, seen.cached);
+        // returns a ref to the schema
+        // defId will be empty if the ref points to an external schema (or #)
         const makeURI = (entry) => {
             // comparing the seen objects because sometimes
             // multiple schemas map to the same seen object.
@@ -540,12 +547,14 @@ class JSONSchemaGenerator {
             if (params.external) {
                 const externalId = params.external.registry.get(entry[0])?.id; // ?? "__shared";// `__schema${this.counter++}`;
                 // check if schema is in the external registry
-                if (externalId)
-                    return { ref: params.external.uri(externalId) };
+                const uriGenerator = params.external.uri ?? ((id) => id);
+                if (externalId) {
+                    return { ref: uriGenerator(externalId) };
+                }
                 // otherwise, add to __shared
                 const id = entry[1].defId ?? entry[1].schema.id ?? `schema${this.counter++}`;
-                entry[1].defId = id;
-                return { defId: id, ref: `${params.external.uri("__shared")}#/${defsSegment}/${id}` };
+                entry[1].defId = id; // set defId so it will be reused if needed
+                return { defId: id, ref: `${uriGenerator("__shared")}#/${defsSegment}/${id}` };
             }
             if (entry[1] === root) {
                 return { ref: "#" };
@@ -559,6 +568,7 @@ class JSONSchemaGenerator {
         // stored cached version in `def` property
         // remove all properties, set $ref
         const extractToDef = (entry) => {
+            // if the schema is already a reference, do not extract it
             if (entry[1].schema.$ref) {
                 return;
             }
@@ -575,14 +585,24 @@ class JSONSchemaGenerator {
             }
             schema.$ref = ref;
         };
+        // throw on cycles
+        // break cycles
+        if (params.cycles === "throw") {
+            for (const entry of this.seen.entries()) {
+                const seen = entry[1];
+                if (seen.cycle) {
+                    throw new Error("Cycle detected: " +
+                        `#/${seen.cycle?.join("/")}/<root>` +
+                        '\n\nSet the `cycles` parameter to `"ref"` to resolve cyclical schemas with defs.');
+                }
+            }
+        }
         // extract schemas into $defs
         for (const entry of this.seen.entries()) {
             const seen = entry[1];
             // convert root schema to # $ref
-            // also prevents root schema from being extracted
             if (schema === entry[0]) {
-                // do not copy to defs...this is the root schema
-                extractToDef(entry);
+                extractToDef(entry); // this has special handling for the root schema
                 continue;
             }
             // extract schemas that are in the external registry
@@ -601,14 +621,8 @@ class JSONSchemaGenerator {
             }
             // break cycles
             if (seen.cycle) {
-                if (params.cycles === "throw") {
-                    throw new Error("Cycle detected: " +
-                        `#/${seen.cycle?.join("/")}/<root>` +
-                        '\n\nSet the `cycles` parameter to `"ref"` to resolve cyclical schemas with defs.');
-                }
-                else if (params.cycles === "ref") {
-                    extractToDef(entry);
-                }
+                // any
+                extractToDef(entry);
                 continue;
             }
             // extract reused schemas
@@ -650,6 +664,7 @@ class JSONSchemaGenerator {
                 this.override({
                     zodSchema: zodSchema,
                     jsonSchema: schema,
+                    path: seen.path ?? [],
                 });
         };
         for (const entry of [...this.seen.entries()].reverse()) {
@@ -665,6 +680,12 @@ class JSONSchemaGenerator {
         else {
             console.warn(`Invalid target: ${this.target}`);
         }
+        if (params.external?.uri) {
+            const id = params.external.registry.get(schema)?.id;
+            if (!id)
+                throw new Error("Schema is missing an `id` property");
+            result.$id = params.external.uri(id);
+        }
         Object.assign(result, root.def);
         // build defs object
         const defs = params.external?.defs ?? {};
@@ -675,12 +696,16 @@ class JSONSchemaGenerator {
             }
         }
         // set definitions in result
-        if (!params.external && Object.keys(defs).length > 0) {
-            if (this.target === "draft-2020-12") {
-                result.$defs = defs;
-            }
-            else {
-                result.definitions = defs;
+        if (params.external) {
+        }
+        else {
+            if (Object.keys(defs).length > 0) {
+                if (this.target === "draft-2020-12") {
+                    result.$defs = defs;
+                }
+                else {
+                    result.definitions = defs;
+                }
             }
         }
         try {
@@ -706,7 +731,7 @@ function toJSONSchema(input, _params) {
         const schemas = {};
         const external = {
             registry: input,
-            uri: _params?.uri || ((id) => id),
+            uri: _params?.uri,
             defs,
         };
         for (const entry of input._idmap.entries()) {

package/v4/core/to-json-schema.d.cts

@@ -17,9 +17,10 @@ interface JSONSchemaGeneratorParams {
     override?: (ctx: {
         zodSchema: schemas.$ZodTypes;
         jsonSchema: JSONSchema.BaseSchema;
+        path: (string | number)[];
     }) => void;
     /** Whether to extract the `"input"` or `"output"` type. Relevant to transforms, Error converting schema to JSONz, defaults, coerced primitives, etc.
-     * - `"output" — Default. Convert the output schema.
+     * - `"output"` — Default. Convert the output schema.
      * - `"input"` — Convert the input schema. */
     io?: "input" | "output";
 }
@@ -38,7 +39,7 @@ interface EmitParams {
         registry: $ZodRegistry<{
             id?: string | undefined;
         }>;
-        uri: (id: string) => string;
+        uri?: ((id: string) => string) | undefined;
         defs: Record<string, JSONSchema.BaseSchema>;
     } | undefined;
 }
@@ -54,6 +55,8 @@ interface Seen {
     cycle?: (string | number)[] | undefined;
     isParent?: boolean | undefined;
     ref?: schemas.$ZodType | undefined | null;
+    /** JSON Schema property path for this schema */
+    path?: (string | number)[] | undefined;
 }
 export declare class JSONSchemaGenerator {
     metadataRegistry: $ZodRegistry<Record<string, any>>;
@@ -62,6 +65,7 @@ export declare class JSONSchemaGenerator {
     override: (ctx: {
         zodSchema: schemas.$ZodTypes;
         jsonSchema: JSONSchema.BaseSchema;
+        path: (string | number)[];
     }) => void;
     io: "input" | "output";
     counter: number;

package/v4/core/to-json-schema.d.ts

@@ -17,9 +17,10 @@ interface JSONSchemaGeneratorParams {
     override?: (ctx: {
         zodSchema: schemas.$ZodTypes;
         jsonSchema: JSONSchema.BaseSchema;
+        path: (string | number)[];
     }) => void;
     /** Whether to extract the `"input"` or `"output"` type. Relevant to transforms, Error converting schema to JSONz, defaults, coerced primitives, etc.
-     * - `"output" — Default. Convert the output schema.
+     * - `"output"` — Default. Convert the output schema.
      * - `"input"` — Convert the input schema. */
     io?: "input" | "output";
 }
@@ -38,7 +39,7 @@ interface EmitParams {
         registry: $ZodRegistry<{
             id?: string | undefined;
         }>;
-        uri: (id: string) => string;
+        uri?: ((id: string) => string) | undefined;
         defs: Record<string, JSONSchema.BaseSchema>;
     } | undefined;
 }
@@ -54,6 +55,8 @@ interface Seen {
     cycle?: (string | number)[] | undefined;
     isParent?: boolean | undefined;
     ref?: schemas.$ZodType | undefined | null;
+    /** JSON Schema property path for this schema */
+    path?: (string | number)[] | undefined;
 }
 export declare class JSONSchemaGenerator {
     metadataRegistry: $ZodRegistry<Record<string, any>>;
@@ -62,6 +65,7 @@ export declare class JSONSchemaGenerator {
     override: (ctx: {
         zodSchema: schemas.$ZodTypes;
         jsonSchema: JSONSchema.BaseSchema;
+        path: (string | number)[];
     }) => void;
     io: "input" | "output";
     counter: number;

package/v4/core/to-json-schema.js

@@ -32,7 +32,7 @@ export class JSONSchemaGenerator {
             return seen.schema;
         }
         // initialize
-        const result = { schema: {}, count: 1, cycle: undefined };
+        const result = { schema: {}, count: 1, cycle: undefined, path: _params.path };
         this.seen.set(schema, result);
         // custom method overrides default behavior
         const overrideSchema = schema._zod.toJSONSchema?.();
@@ -147,9 +147,10 @@ export class JSONSchemaGenerator {
                     case "unknown": {
                         break;
                     }
-                    case "undefined":
-                    case "never": {
-                        _json.not = {};
+                    case "undefined": {
+                        if (this.unrepresentable === "throw") {
+                            throw new Error("Undefined cannot be represented in JSON Schema");
+                        }
                         break;
                     }
                     case "void": {
@@ -158,6 +159,10 @@ export class JSONSchemaGenerator {
                         }
                         break;
                     }
+                    case "never": {
+                        _json.not = {};
+                        break;
+                    }
                     case "date": {
                         if (this.unrepresentable === "throw") {
                             throw new Error("Date cannot be represented in JSON Schema");
@@ -527,6 +532,8 @@ export class JSONSchemaGenerator {
             throw new Error("Unprocessed schema. This is a bug in Zod.");
         // initialize result with root schema fields
         // Object.assign(result, seen.cached);
+        // returns a ref to the schema
+        // defId will be empty if the ref points to an external schema (or #)
         const makeURI = (entry) => {
             // comparing the seen objects because sometimes
             // multiple schemas map to the same seen object.
@@ -536,12 +543,14 @@ export class JSONSchemaGenerator {
             if (params.external) {
                 const externalId = params.external.registry.get(entry[0])?.id; // ?? "__shared";// `__schema${this.counter++}`;
                 // check if schema is in the external registry
-                if (externalId)
-                    return { ref: params.external.uri(externalId) };
+                const uriGenerator = params.external.uri ?? ((id) => id);
+                if (externalId) {
+                    return { ref: uriGenerator(externalId) };
+                }
                 // otherwise, add to __shared
                 const id = entry[1].defId ?? entry[1].schema.id ?? `schema${this.counter++}`;
-                entry[1].defId = id;
-                return { defId: id, ref: `${params.external.uri("__shared")}#/${defsSegment}/${id}` };
+                entry[1].defId = id; // set defId so it will be reused if needed
+                return { defId: id, ref: `${uriGenerator("__shared")}#/${defsSegment}/${id}` };
             }
             if (entry[1] === root) {
                 return { ref: "#" };
@@ -555,6 +564,7 @@ export class JSONSchemaGenerator {
         // stored cached version in `def` property
         // remove all properties, set $ref
         const extractToDef = (entry) => {
+            // if the schema is already a reference, do not extract it
             if (entry[1].schema.$ref) {
                 return;
             }
@@ -571,14 +581,24 @@ export class JSONSchemaGenerator {
             }
             schema.$ref = ref;
         };
+        // throw on cycles
+        // break cycles
+        if (params.cycles === "throw") {
+            for (const entry of this.seen.entries()) {
+                const seen = entry[1];
+                if (seen.cycle) {
+                    throw new Error("Cycle detected: " +
+                        `#/${seen.cycle?.join("/")}/<root>` +
+                        '\n\nSet the `cycles` parameter to `"ref"` to resolve cyclical schemas with defs.');
+                }
+            }
+        }
         // extract schemas into $defs
         for (const entry of this.seen.entries()) {
             const seen = entry[1];
             // convert root schema to # $ref
-            // also prevents root schema from being extracted
             if (schema === entry[0]) {
-                // do not copy to defs...this is the root schema
-                extractToDef(entry);
+                extractToDef(entry); // this has special handling for the root schema
                 continue;
             }
             // extract schemas that are in the external registry
@@ -597,14 +617,8 @@ export class JSONSchemaGenerator {
             }
             // break cycles
             if (seen.cycle) {
-                if (params.cycles === "throw") {
-                    throw new Error("Cycle detected: " +
-                        `#/${seen.cycle?.join("/")}/<root>` +
-                        '\n\nSet the `cycles` parameter to `"ref"` to resolve cyclical schemas with defs.');
-                }
-                else if (params.cycles === "ref") {
-                    extractToDef(entry);
-                }
+                // any
+                extractToDef(entry);
                 continue;
             }
             // extract reused schemas
@@ -646,6 +660,7 @@ export class JSONSchemaGenerator {
                 this.override({
                     zodSchema: zodSchema,
                     jsonSchema: schema,
+                    path: seen.path ?? [],
                 });
         };
         for (const entry of [...this.seen.entries()].reverse()) {
@@ -661,6 +676,12 @@ export class JSONSchemaGenerator {
         else {
             console.warn(`Invalid target: ${this.target}`);
         }
+        if (params.external?.uri) {
+            const id = params.external.registry.get(schema)?.id;
+            if (!id)
+                throw new Error("Schema is missing an `id` property");
+            result.$id = params.external.uri(id);
+        }
         Object.assign(result, root.def);
         // build defs object
         const defs = params.external?.defs ?? {};
@@ -671,12 +692,16 @@ export class JSONSchemaGenerator {
             }
         }
         // set definitions in result
-        if (!params.external && Object.keys(defs).length > 0) {
-            if (this.target === "draft-2020-12") {
-                result.$defs = defs;
-            }
-            else {
-                result.definitions = defs;
+        if (params.external) {
+        }
+        else {
+            if (Object.keys(defs).length > 0) {
+                if (this.target === "draft-2020-12") {
+                    result.$defs = defs;
+                }
+                else {
+                    result.definitions = defs;
+                }
             }
         }
         try {
@@ -701,7 +726,7 @@ export function toJSONSchema(input, _params) {
         const schemas = {};
         const external = {
             registry: input,
-            uri: _params?.uri || ((id) => id),
+            uri: _params?.uri,
             defs,
         };
         for (const entry of input._idmap.entries()) {

package/v4/mini/schemas.d.cts

@@ -234,7 +234,7 @@ export interface ZodMiniRecord<Key extends core.$ZodRecordKey = core.$ZodRecordK
 }
 export declare const ZodMiniRecord: core.$constructor<ZodMiniRecord>;
 export declare function record<Key extends core.$ZodRecordKey, Value extends SomeType>(keyType: Key, valueType: Value, params?: string | core.$ZodRecordParams): ZodMiniRecord<Key, Value>;
-export declare function partialRecord<Key extends core.$ZodRecordKey, Value extends SomeType>(keyType: Key, valueType: Value, params?: string | core.$ZodRecordParams): ZodMiniRecord<ZodMiniUnion<[Key, ZodMiniNever]>, Value>;
+export declare function partialRecord<Key extends core.$ZodRecordKey, Value extends SomeType>(keyType: Key, valueType: Value, params?: string | core.$ZodRecordParams): ZodMiniRecord<Key & core.$partial, Value>;
 export interface ZodMiniMap<Key extends SomeType = core.$ZodType, Value extends SomeType = core.$ZodType> extends _ZodMiniType<core.$ZodMapInternals<Key, Value>> {
 }
 export declare const ZodMiniMap: core.$constructor<ZodMiniMap>;

package/v4/mini/schemas.d.ts

@@ -234,7 +234,7 @@ export interface ZodMiniRecord<Key extends core.$ZodRecordKey = core.$ZodRecordK
 }
 export declare const ZodMiniRecord: core.$constructor<ZodMiniRecord>;
 export declare function record<Key extends core.$ZodRecordKey, Value extends SomeType>(keyType: Key, valueType: Value, params?: string | core.$ZodRecordParams): ZodMiniRecord<Key, Value>;
-export declare function partialRecord<Key extends core.$ZodRecordKey, Value extends SomeType>(keyType: Key, valueType: Value, params?: string | core.$ZodRecordParams): ZodMiniRecord<ZodMiniUnion<[Key, ZodMiniNever]>, Value>;
+export declare function partialRecord<Key extends core.$ZodRecordKey, Value extends SomeType>(keyType: Key, valueType: Value, params?: string | core.$ZodRecordParams): ZodMiniRecord<Key & core.$partial, Value>;
 export interface ZodMiniMap<Key extends SomeType = core.$ZodType, Value extends SomeType = core.$ZodType> extends _ZodMiniType<core.$ZodMapInternals<Key, Value>> {
 }
 export declare const ZodMiniMap: core.$constructor<ZodMiniMap>;