zod 3.26.0-canary.20250707T201657 → 3.26.0-canary.20250708T090717

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zod",
-  "version": "3.26.0-canary.20250707T201657",
+  "version": "3.26.0-canary.20250708T090717",
   "type": "module",
   "author": "Colin McDonnell <zod@colinhacks.com>",
   "description": "TypeScript-first schema declaration and validation library with static type inference",

package/src/v4/classic/schemas.ts

@@ -1937,10 +1937,10 @@ export const ZodCustom: core.$constructor<ZodCustom> = /*@__PURE__*/ core.$const
 });
 
 // custom checks
-export function check<O = unknown>(fn: core.CheckFn<O>, params?: string | core.$ZodCustomParams): core.$ZodCheck<O> {
+export function check<O = unknown>(fn: core.CheckFn<O>): core.$ZodCheck<O> {
   const ch = new core.$ZodCheck({
     check: "custom",
-    ...util.normalizeParams(params),
+    // ...util.normalizeParams(params),
   });
 
   ch._zod.check = fn;
@@ -1962,10 +1962,7 @@ export function refine<T>(
 }
 
 // superRefine
-export function superRefine<T>(
-  fn: (arg: T, payload: RefinementCtx<T>) => void | Promise<void>,
-  params?: string | core.$ZodCustomParams
-): core.$ZodCheck<T> {
+export function superRefine<T>(fn: (arg: T, payload: RefinementCtx<T>) => void | Promise<void>): core.$ZodCheck<T> {
   const ch = check<T>((payload) => {
     (payload as RefinementCtx).addIssue = (issue) => {
       if (typeof issue === "string") {
@@ -1983,7 +1980,7 @@ export function superRefine<T>(
     };
 
     return fn(payload.value, payload as RefinementCtx<T>);
-  }, params);
+  });
   return ch;
 }
 

package/src/v4/classic/tests/recursive-types.test.ts

@@ -324,3 +324,33 @@ test("recursion compatibility", () => {
     },
   });
 });
+
+// biome-ignore lint: sadf
+export type RecursiveA = z.ZodUnion<
+  [
+    z.ZodObject<{
+      a: z.ZodDefault<RecursiveA>;
+      b: z.ZodPrefault<RecursiveA>;
+      c: z.ZodNonOptional<RecursiveA>;
+      d: z.ZodOptional<RecursiveA>;
+      e: z.ZodNullable<RecursiveA>;
+      g: z.ZodReadonly<RecursiveA>;
+      h: z.ZodPipe<RecursiveA, z.ZodString>;
+      i: z.ZodArray<RecursiveA>;
+      j: z.ZodSet<RecursiveA>;
+      k: z.ZodMap<RecursiveA, RecursiveA>;
+      l: z.ZodRecord<z.ZodString, RecursiveA>;
+      m: z.ZodUnion<[RecursiveA, RecursiveA]>;
+      n: z.ZodIntersection<RecursiveA, RecursiveA>;
+      o: z.ZodLazy<RecursiveA>;
+      p: z.ZodPromise<RecursiveA>;
+      q: z.ZodCatch<RecursiveA>;
+      r: z.ZodSuccess<RecursiveA>;
+      s: z.ZodTransform<RecursiveA, string>;
+      t: z.ZodTuple<[RecursiveA, RecursiveA]>;
+      u: z.ZodObject<{
+        a: RecursiveA;
+      }>;
+    }>,
+  ]
+>;

package/src/v4/classic/tests/refine.test.ts

@@ -421,3 +421,112 @@ describe("type refinement", () => {
   });
 });
 */
+
+test("when", () => {
+  const schema = z
+    .strictObject({
+      password: z.string().min(8),
+      confirmPassword: z.string(),
+      other: z.string(),
+    })
+    .refine(
+      (data) => {
+        console.log("running check...");
+        console.log(data);
+        console.log(data.password);
+        return data.password === data.confirmPassword;
+      },
+      {
+        message: "Passwords do not match",
+        path: ["confirmPassword"],
+        when(payload) {
+          if (payload.value === undefined) return false;
+          if (payload.value === null) return false;
+          // no issues with confirmPassword or password
+          return payload.issues.every((iss) => iss.path?.[0] !== "confirmPassword" && iss.path?.[0] !== "password");
+        },
+      }
+    );
+
+  expect(schema.safeParse(undefined)).toMatchInlineSnapshot(`
+    {
+      "error": [ZodError: [
+      {
+        "expected": "object",
+        "code": "invalid_type",
+        "path": [],
+        "message": "Invalid input: expected object, received undefined"
+      }
+    ]],
+      "success": false,
+    }
+  `);
+  expect(schema.safeParse(null)).toMatchInlineSnapshot(`
+    {
+      "error": [ZodError: [
+      {
+        "expected": "object",
+        "code": "invalid_type",
+        "path": [],
+        "message": "Invalid input: expected object, received null"
+      }
+    ]],
+      "success": false,
+    }
+  `);
+  expect(
+    schema.safeParse({
+      password: "asdf",
+      confirmPassword: "asdfg",
+      other: "qwer",
+    })
+  ).toMatchInlineSnapshot(`
+    {
+      "error": [ZodError: [
+      {
+        "origin": "string",
+        "code": "too_small",
+        "minimum": 8,
+        "inclusive": true,
+        "path": [
+          "password"
+        ],
+        "message": "Too small: expected string to have >=8 characters"
+      }
+    ]],
+      "success": false,
+    }
+  `);
+
+  expect(
+    schema.safeParse({
+      password: "asdf",
+      confirmPassword: "asdfg",
+      other: 1234,
+    })
+  ).toMatchInlineSnapshot(`
+    {
+      "error": [ZodError: [
+      {
+        "origin": "string",
+        "code": "too_small",
+        "minimum": 8,
+        "inclusive": true,
+        "path": [
+          "password"
+        ],
+        "message": "Too small: expected string to have >=8 characters"
+      },
+      {
+        "expected": "string",
+        "code": "invalid_type",
+        "path": [
+          "other"
+        ],
+        "message": "Invalid input: expected string, received number"
+      }
+    ]],
+      "success": false,
+    }
+  `);
+});

package/src/v4/classic/tests/registries.test.ts

@@ -193,3 +193,12 @@ test("function meta with replacement", () => {
 
   expect(myReg.get(mySchema)!.defaulter("hello", true)).toEqual(5);
 });
+
+test("test .clear()", () => {
+  const reg = z.registry();
+  const a = z.string();
+  reg.add(a);
+  expect(reg.has(a)).toEqual(true);
+  reg.clear();
+  expect(reg.has(a)).toEqual(false);
+});

package/src/v4/classic/tests/to-json-schema.test.ts

@@ -1746,16 +1746,17 @@ test("basic registry", () => {
   myRegistry.add(User, { id: "User" });
   myRegistry.add(Post, { id: "Post" });
 
-  const result = z.z.toJSONSchema(myRegistry);
+  const result = z.z.toJSONSchema(myRegistry, { uri: (id) => `https://example.com/${id}.json` });
   expect(result).toMatchInlineSnapshot(`
     {
       "schemas": {
         "Post": {
+          "$id": "https://example.com/Post.json",
           "$schema": "https://json-schema.org/draft/2020-12/schema",
           "additionalProperties": false,
           "properties": {
             "author": {
-              "$ref": "User",
+              "$ref": "https://example.com/User.json",
             },
             "content": {
               "type": "string",
@@ -1772,6 +1773,7 @@ test("basic registry", () => {
           "type": "object",
         },
         "User": {
+          "$id": "https://example.com/User.json",
           "$schema": "https://json-schema.org/draft/2020-12/schema",
           "additionalProperties": false,
           "properties": {
@@ -1780,7 +1782,7 @@ test("basic registry", () => {
             },
             "posts": {
               "items": {
-                "$ref": "Post",
+                "$ref": "https://example.com/Post.json",
               },
               "type": "array",
             },
@@ -2273,3 +2275,40 @@ test("custom toJSONSchema", () => {
     }
   `);
 });
+
+test("cycle detection - root", () => {
+  const schema = z.object({
+    name: z.string(),
+    get subcategories() {
+      return z.array(schema);
+    },
+  });
+
+  expect(() => z.toJSONSchema(schema, { cycles: "throw" })).toThrowErrorMatchingInlineSnapshot(`
+    [Error: Cycle detected: #/properties/subcategories/items/<root>
+
+    Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.]
+  `);
+});
+
+test("cycle detection - mutual recursion", () => {
+  const A = z.object({
+    name: z.string(),
+    get subcategories() {
+      return z.array(B);
+    },
+  });
+
+  const B = z.object({
+    name: z.string(),
+    get subcategories() {
+      return z.array(A);
+    },
+  });
+
+  expect(() => z.toJSONSchema(A, { cycles: "throw" })).toThrowErrorMatchingInlineSnapshot(`
+    [Error: Cycle detected: #/properties/subcategories/items/properties/subcategories/items/<root>
+
+    Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.]
+  `);
+});

package/src/v4/core/api.ts

@@ -779,6 +779,8 @@ export function _nan<T extends schemas.$ZodNaN>(Class: util.SchemaClass<T>, para
   });
 }
 
+// export type $ZodCheckParams = CheckParams<checks.$ZodCheck, "abort">;
+
 export type $ZodCheckLessThanParams = CheckParams<checks.$ZodCheckLessThan, "inclusive" | "value">;
 export function _lt(
   value: util.Numeric,

package/src/v4/core/checks.ts

@@ -13,18 +13,16 @@ export interface $ZodCheckDef {
   error?: errors.$ZodErrorMap<never> | undefined;
   /** If true, no later checks will be executed if this check fails. Default `false`. */
   abort?: boolean | undefined;
+  /** If provided, this check will only be executed if the function returns `true`. Defaults to `payload => z.util.isAborted(payload)`. */
+  when?: ((payload: schemas.ParsePayload) => boolean) | undefined;
 }
 
 export interface $ZodCheckInternals<T> {
   def: $ZodCheckDef;
   /** The set of issues this check might throw. */
   issc?: errors.$ZodIssueBase;
-  // "_check"(input: $ZodResult<T>): util.MaybeAsync<void>;
   check(payload: schemas.ParsePayload<T>): util.MaybeAsync<void>;
-  // _parseB(payload: ParsePayload<any>, ctx: ParseContext): util.MaybeAsync<ParsePayload>;
   onattach: ((schema: schemas.$ZodType) => void)[];
-  // "_async": boolean;
-  when?: ((payload: schemas.ParsePayload) => boolean) | undefined;
 }
 
 export interface $ZodCheck<in T = never> {
@@ -452,7 +450,7 @@ export const $ZodCheckMaxSize: core.$constructor<$ZodCheckMaxSize> = /*@__PURE__
   (inst, def) => {
     $ZodCheck.init(inst, def);
 
-    inst._zod.when = (payload) => {
+    inst._zod.def.when ??= (payload) => {
       const val = payload.value;
       return !util.nullish(val) && (val as any).size !== undefined;
     };
@@ -501,7 +499,7 @@ export const $ZodCheckMinSize: core.$constructor<$ZodCheckMinSize> = /*@__PURE__
   (inst, def) => {
     $ZodCheck.init(inst, def);
 
-    inst._zod.when = (payload) => {
+    inst._zod.def.when ??= (payload) => {
       const val = payload.value;
       return !util.nullish(val) && (val as any).size !== undefined;
     };
@@ -550,7 +548,7 @@ export const $ZodCheckSizeEquals: core.$constructor<$ZodCheckSizeEquals> = /*@__
   (inst, def) => {
     $ZodCheck.init(inst, def);
 
-    inst._zod.when = (payload) => {
+    inst._zod.def.when ??= (payload) => {
       const val = payload.value;
       return !util.nullish(val) && (val as any).size !== undefined;
     };
@@ -604,7 +602,7 @@ export const $ZodCheckMaxLength: core.$constructor<$ZodCheckMaxLength> = /*@__PU
   (inst, def) => {
     $ZodCheck.init(inst, def);
 
-    inst._zod.when = (payload) => {
+    inst._zod.def.when ??= (payload) => {
       const val = payload.value;
       return !util.nullish(val) && (val as any).length !== undefined;
     };
@@ -655,7 +653,7 @@ export const $ZodCheckMinLength: core.$constructor<$ZodCheckMinLength> = /*@__PU
   (inst, def) => {
     $ZodCheck.init(inst, def);
 
-    inst._zod.when = (payload) => {
+    inst._zod.def.when ??= (payload) => {
       const val = payload.value;
       return !util.nullish(val) && (val as any).length !== undefined;
     };
@@ -707,7 +705,7 @@ export const $ZodCheckLengthEquals: core.$constructor<$ZodCheckLengthEquals> = /
   (inst, def) => {
     $ZodCheck.init(inst, def);
 
-    inst._zod.when = (payload) => {
+    inst._zod.def.when ??= (payload) => {
       const val = payload.value;
       return !util.nullish(val) && (val as any).length !== undefined;
     };

package/src/v4/core/errors.ts

@@ -203,6 +203,10 @@ const initializer = (inst: $ZodError, def: $ZodIssue[]): void => {
     enumerable: true,
     // configurable: false,
   });
+  Object.defineProperty(inst, "toString", {
+    value: () => inst.message,
+    enumerable: false,
+  });
 };
 
 export const $ZodError: $constructor<$ZodError> = $constructor("$ZodError", initializer);

package/src/v4/core/registries.ts

@@ -27,7 +27,7 @@ type MetadataType = Record<string, unknown> | undefined;
 export class $ZodRegistry<Meta extends MetadataType = MetadataType, Schema extends $ZodType = $ZodType> {
   _meta!: Meta;
   _schema!: Schema;
-  _map: WeakMap<Schema, $replace<Meta, Schema>> = new WeakMap();
+  _map: Map<Schema, $replace<Meta, Schema>> = new Map();
   _idmap: Map<string, Schema> = new Map();
 
   add<S extends Schema>(
@@ -45,6 +45,12 @@ export class $ZodRegistry<Meta extends MetadataType = MetadataType, Schema exten
     return this as any;
   }
 
+  clear(): this {
+    this._map = new Map();
+    this._idmap = new Map();
+    return this;
+  }
+
   remove(schema: Schema): this {
     const meta: any = this._map.get(schema);
     if (meta && typeof meta === "object" && "id" in meta) {

package/src/v4/core/schemas.ts

@@ -204,18 +204,18 @@ export const $ZodType: core.$constructor<$ZodType> = /*@__PURE__*/ core.$constru
       ctx?: ParseContextInternal | undefined
     ): util.MaybeAsync<ParsePayload> => {
       let isAborted = util.aborted(payload);
+
       let asyncResult!: Promise<unknown> | undefined;
       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;
         } else if (isAborted) {
           continue;
         }
-
         const currLen = payload.issues.length;
         const _ = ch._zod.check(payload as any) as any as ParsePayload;
+
         if (_ instanceof Promise && ctx?.async === false) {
           throw new core.$ZodAsyncError();
         }

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

@@ -47,7 +47,7 @@ interface EmitParams {
     | {
         /**  */
         registry: $ZodRegistry<{ id?: string | undefined }>;
-        uri: (id: string) => string;
+        uri?: ((id: string) => string) | undefined;
         defs: Record<string, JSONSchema.BaseSchema>;
       }
     | undefined;
@@ -614,6 +614,8 @@ export class JSONSchemaGenerator {
     // 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: [schemas.$ZodType<unknown, unknown>, Seen]): { ref: string; defId?: string } => {
       // comparing the seen objects because sometimes
       // multiple schemas map to the same seen object.
@@ -625,12 +627,15 @@ export class JSONSchemaGenerator {
         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: string = entry[1].defId ?? (entry[1].schema.id as string) ?? `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) {
@@ -647,6 +652,7 @@ export class JSONSchemaGenerator {
     // stored cached version in `def` property
     // remove all properties, set $ref
     const extractToDef = (entry: [schemas.$ZodType<unknown, unknown>, Seen]): void => {
+      // if the schema is already a reference, do not extract it
       if (entry[1].schema.$ref) {
         return;
       }
@@ -664,15 +670,29 @@ 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;
       }
 
@@ -689,21 +709,13 @@ export class JSONSchemaGenerator {
       const id = this.metadataRegistry.get(entry[0])?.id;
       if (id) {
         extractToDef(entry);
-
         continue;
       }
 
       // 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;
       }
 
@@ -768,6 +780,12 @@ export class JSONSchemaGenerator {
       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
@@ -780,11 +798,14 @@ 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;
+        }
       }
     }
 
@@ -824,7 +845,7 @@ export function toJSONSchema(
     const schemas: Record<string, JSONSchema.BaseSchema> = {};
     const external = {
       registry: input,
-      uri: (_params as RegistryToJSONSchemaParams)?.uri || ((id) => id),
+      uri: (_params as RegistryToJSONSchemaParams)?.uri,
       defs,
     };
     for (const entry of input._idmap.entries()) {

package/v4/classic/schemas.cjs

@@ -1038,10 +1038,10 @@ exports.ZodCustom = core.$constructor("ZodCustom", (inst, def) => {
     exports.ZodType.init(inst, def);
 });
 // custom checks
-function check(fn, params) {
+function check(fn) {
     const ch = new core.$ZodCheck({
         check: "custom",
-        ...index_js_1.util.normalizeParams(params),
+        // ...util.normalizeParams(params),
     });
     ch._zod.check = fn;
     return ch;
@@ -1053,7 +1053,7 @@ function refine(fn, _params = {}) {
     return core._refine(exports.ZodCustom, fn, _params);
 }
 // superRefine
-function superRefine(fn, params) {
+function superRefine(fn) {
     const ch = check((payload) => {
         payload.addIssue = (issue) => {
             if (typeof issue === "string") {
@@ -1072,7 +1072,7 @@ function superRefine(fn, params) {
             }
         };
         return fn(payload.value, payload);
-    }, params);
+    });
     return ch;
 }
 function _instanceof(cls, params = {

package/v4/classic/schemas.d.cts

@@ -602,10 +602,10 @@ export declare function promise<T extends core.SomeType>(innerType: T): ZodPromi
 export interface ZodCustom<O = unknown, I = unknown> extends _ZodType<core.$ZodCustomInternals<O, I>>, core.$ZodCustom<O, I> {
 }
 export declare const ZodCustom: core.$constructor<ZodCustom>;
-export declare function check<O = unknown>(fn: core.CheckFn<O>, params?: string | core.$ZodCustomParams): core.$ZodCheck<O>;
+export declare function check<O = unknown>(fn: core.CheckFn<O>): core.$ZodCheck<O>;
 export declare function custom<O>(fn?: (data: unknown) => unknown, _params?: string | core.$ZodCustomParams | undefined): ZodCustom<O, O>;
 export declare function refine<T>(fn: (arg: NoInfer<T>) => util.MaybeAsync<unknown>, _params?: string | core.$ZodCustomParams): core.$ZodCheck<T>;
-export declare function superRefine<T>(fn: (arg: T, payload: RefinementCtx<T>) => void | Promise<void>, params?: string | core.$ZodCustomParams): core.$ZodCheck<T>;
+export declare function superRefine<T>(fn: (arg: T, payload: RefinementCtx<T>) => void | Promise<void>): core.$ZodCheck<T>;
 type ZodInstanceOfParams = core.Params<ZodCustom, core.$ZodIssueCustom, "type" | "check" | "checks" | "fn" | "abort" | "error" | "params" | "path">;
 declare function _instanceof<T extends typeof util.Class>(cls: T, params?: ZodInstanceOfParams): ZodCustom<InstanceType<T>, InstanceType<T>>;
 export { _instanceof as instanceof };

package/v4/classic/schemas.d.ts

@@ -602,10 +602,10 @@ export declare function promise<T extends core.SomeType>(innerType: T): ZodPromi
 export interface ZodCustom<O = unknown, I = unknown> extends _ZodType<core.$ZodCustomInternals<O, I>>, core.$ZodCustom<O, I> {
 }
 export declare const ZodCustom: core.$constructor<ZodCustom>;
-export declare function check<O = unknown>(fn: core.CheckFn<O>, params?: string | core.$ZodCustomParams): core.$ZodCheck<O>;
+export declare function check<O = unknown>(fn: core.CheckFn<O>): core.$ZodCheck<O>;
 export declare function custom<O>(fn?: (data: unknown) => unknown, _params?: string | core.$ZodCustomParams | undefined): ZodCustom<O, O>;
 export declare function refine<T>(fn: (arg: NoInfer<T>) => util.MaybeAsync<unknown>, _params?: string | core.$ZodCustomParams): core.$ZodCheck<T>;
-export declare function superRefine<T>(fn: (arg: T, payload: RefinementCtx<T>) => void | Promise<void>, params?: string | core.$ZodCustomParams): core.$ZodCheck<T>;
+export declare function superRefine<T>(fn: (arg: T, payload: RefinementCtx<T>) => void | Promise<void>): core.$ZodCheck<T>;
 type ZodInstanceOfParams = core.Params<ZodCustom, core.$ZodIssueCustom, "type" | "check" | "checks" | "fn" | "abort" | "error" | "params" | "path">;
 declare function _instanceof<T extends typeof util.Class>(cls: T, params?: ZodInstanceOfParams): ZodCustom<InstanceType<T>, InstanceType<T>>;
 export { _instanceof as instanceof };

package/v4/classic/schemas.js

@@ -935,10 +935,10 @@ export const ZodCustom = /*@__PURE__*/ core.$constructor("ZodCustom", (inst, def
     ZodType.init(inst, def);
 });
 // custom checks
-export function check(fn, params) {
+export function check(fn) {
     const ch = new core.$ZodCheck({
         check: "custom",
-        ...util.normalizeParams(params),
+        // ...util.normalizeParams(params),
     });
     ch._zod.check = fn;
     return ch;
@@ -950,7 +950,7 @@ export function refine(fn, _params = {}) {
     return core._refine(ZodCustom, fn, _params);
 }
 // superRefine
-export function superRefine(fn, params) {
+export function superRefine(fn) {
     const ch = check((payload) => {
         payload.addIssue = (issue) => {
             if (typeof issue === "string") {
@@ -969,7 +969,7 @@ export function superRefine(fn, params) {
             }
         };
         return fn(payload.value, payload);
-    }, params);
+    });
     return ch;
 }
 function _instanceof(cls, params = {

package/v4/core/checks.cjs

@@ -248,11 +248,12 @@ exports.$ZodCheckBigIntFormat = core.$constructor("$ZodCheckBigIntFormat", (inst
     };
 });
 exports.$ZodCheckMaxSize = core.$constructor("$ZodCheckMaxSize", (inst, def) => {
+    var _a;
     exports.$ZodCheck.init(inst, def);
-    inst._zod.when = (payload) => {
+    (_a = inst._zod.def).when ?? (_a.when = (payload) => {
         const val = payload.value;
         return !util.nullish(val) && val.size !== undefined;
-    };
+    });
     inst._zod.onattach.push((inst) => {
         const curr = (inst._zod.bag.maximum ?? Number.POSITIVE_INFINITY);
         if (def.maximum < curr)
@@ -274,11 +275,12 @@ exports.$ZodCheckMaxSize = core.$constructor("$ZodCheckMaxSize", (inst, def) =>
     };
 });
 exports.$ZodCheckMinSize = core.$constructor("$ZodCheckMinSize", (inst, def) => {
+    var _a;
     exports.$ZodCheck.init(inst, def);
-    inst._zod.when = (payload) => {
+    (_a = inst._zod.def).when ?? (_a.when = (payload) => {
         const val = payload.value;
         return !util.nullish(val) && val.size !== undefined;
-    };
+    });
     inst._zod.onattach.push((inst) => {
         const curr = (inst._zod.bag.minimum ?? Number.NEGATIVE_INFINITY);
         if (def.minimum > curr)
@@ -300,11 +302,12 @@ exports.$ZodCheckMinSize = core.$constructor("$ZodCheckMinSize", (inst, def) =>
     };
 });
 exports.$ZodCheckSizeEquals = core.$constructor("$ZodCheckSizeEquals", (inst, def) => {
+    var _a;
     exports.$ZodCheck.init(inst, def);
-    inst._zod.when = (payload) => {
+    (_a = inst._zod.def).when ?? (_a.when = (payload) => {
         const val = payload.value;
         return !util.nullish(val) && val.size !== undefined;
-    };
+    });
     inst._zod.onattach.push((inst) => {
         const bag = inst._zod.bag;
         bag.minimum = def.size;
@@ -329,11 +332,12 @@ exports.$ZodCheckSizeEquals = core.$constructor("$ZodCheckSizeEquals", (inst, de
     };
 });
 exports.$ZodCheckMaxLength = core.$constructor("$ZodCheckMaxLength", (inst, def) => {
+    var _a;
     exports.$ZodCheck.init(inst, def);
-    inst._zod.when = (payload) => {
+    (_a = inst._zod.def).when ?? (_a.when = (payload) => {
         const val = payload.value;
         return !util.nullish(val) && val.length !== undefined;
-    };
+    });
     inst._zod.onattach.push((inst) => {
         const curr = (inst._zod.bag.maximum ?? Number.POSITIVE_INFINITY);
         if (def.maximum < curr)
@@ -357,11 +361,12 @@ exports.$ZodCheckMaxLength = core.$constructor("$ZodCheckMaxLength", (inst, def)
     };
 });
 exports.$ZodCheckMinLength = core.$constructor("$ZodCheckMinLength", (inst, def) => {
+    var _a;
     exports.$ZodCheck.init(inst, def);
-    inst._zod.when = (payload) => {
+    (_a = inst._zod.def).when ?? (_a.when = (payload) => {
         const val = payload.value;
         return !util.nullish(val) && val.length !== undefined;
-    };
+    });
     inst._zod.onattach.push((inst) => {
         const curr = (inst._zod.bag.minimum ?? Number.NEGATIVE_INFINITY);
         if (def.minimum > curr)
@@ -385,11 +390,12 @@ exports.$ZodCheckMinLength = core.$constructor("$ZodCheckMinLength", (inst, def)
     };
 });
 exports.$ZodCheckLengthEquals = core.$constructor("$ZodCheckLengthEquals", (inst, def) => {
+    var _a;
     exports.$ZodCheck.init(inst, def);
-    inst._zod.when = (payload) => {
+    (_a = inst._zod.def).when ?? (_a.when = (payload) => {
         const val = payload.value;
         return !util.nullish(val) && val.length !== undefined;
-    };
+    });
     inst._zod.onattach.push((inst) => {
         const bag = inst._zod.bag;
         bag.minimum = def.length;

package/v4/core/checks.d.cts

@@ -7,6 +7,8 @@ export interface $ZodCheckDef {
     error?: errors.$ZodErrorMap<never> | undefined;
     /** If true, no later checks will be executed if this check fails. Default `false`. */
     abort?: boolean | undefined;
+    /** If provided, this check will only be executed if the function returns `true`. Defaults to `payload => z.util.isAborted(payload)`. */
+    when?: ((payload: schemas.ParsePayload) => boolean) | undefined;
 }
 export interface $ZodCheckInternals<T> {
     def: $ZodCheckDef;
@@ -14,7 +16,6 @@ export interface $ZodCheckInternals<T> {
     issc?: errors.$ZodIssueBase;
     check(payload: schemas.ParsePayload<T>): util.MaybeAsync<void>;
     onattach: ((schema: schemas.$ZodType) => void)[];
-    when?: ((payload: schemas.ParsePayload) => boolean) | undefined;
 }
 export interface $ZodCheck<in T = never> {
     _zod: $ZodCheckInternals<T>;

package/v4/core/checks.d.ts

@@ -7,6 +7,8 @@ export interface $ZodCheckDef {
     error?: errors.$ZodErrorMap<never> | undefined;
     /** If true, no later checks will be executed if this check fails. Default `false`. */
     abort?: boolean | undefined;
+    /** If provided, this check will only be executed if the function returns `true`. Defaults to `payload => z.util.isAborted(payload)`. */
+    when?: ((payload: schemas.ParsePayload) => boolean) | undefined;
 }
 export interface $ZodCheckInternals<T> {
     def: $ZodCheckDef;
@@ -14,7 +16,6 @@ export interface $ZodCheckInternals<T> {
     issc?: errors.$ZodIssueBase;
     check(payload: schemas.ParsePayload<T>): util.MaybeAsync<void>;
     onattach: ((schema: schemas.$ZodType) => void)[];
-    when?: ((payload: schemas.ParsePayload) => boolean) | undefined;
 }
 export interface $ZodCheck<in T = never> {
     _zod: $ZodCheckInternals<T>;

package/v4/core/checks.js

@@ -222,11 +222,12 @@ export const $ZodCheckBigIntFormat = /*@__PURE__*/ core.$constructor("$ZodCheckB
     };
 });
 export const $ZodCheckMaxSize = /*@__PURE__*/ core.$constructor("$ZodCheckMaxSize", (inst, def) => {
+    var _a;
     $ZodCheck.init(inst, def);
-    inst._zod.when = (payload) => {
+    (_a = inst._zod.def).when ?? (_a.when = (payload) => {
         const val = payload.value;
         return !util.nullish(val) && val.size !== undefined;
-    };
+    });
     inst._zod.onattach.push((inst) => {
         const curr = (inst._zod.bag.maximum ?? Number.POSITIVE_INFINITY);
         if (def.maximum < curr)
@@ -248,11 +249,12 @@ export const $ZodCheckMaxSize = /*@__PURE__*/ core.$constructor("$ZodCheckMaxSiz
     };
 });
 export const $ZodCheckMinSize = /*@__PURE__*/ core.$constructor("$ZodCheckMinSize", (inst, def) => {
+    var _a;
     $ZodCheck.init(inst, def);
-    inst._zod.when = (payload) => {
+    (_a = inst._zod.def).when ?? (_a.when = (payload) => {
         const val = payload.value;
         return !util.nullish(val) && val.size !== undefined;
-    };
+    });
     inst._zod.onattach.push((inst) => {
         const curr = (inst._zod.bag.minimum ?? Number.NEGATIVE_INFINITY);
         if (def.minimum > curr)
@@ -274,11 +276,12 @@ export const $ZodCheckMinSize = /*@__PURE__*/ core.$constructor("$ZodCheckMinSiz
     };
 });
 export const $ZodCheckSizeEquals = /*@__PURE__*/ core.$constructor("$ZodCheckSizeEquals", (inst, def) => {
+    var _a;
     $ZodCheck.init(inst, def);
-    inst._zod.when = (payload) => {
+    (_a = inst._zod.def).when ?? (_a.when = (payload) => {
         const val = payload.value;
         return !util.nullish(val) && val.size !== undefined;
-    };
+    });
     inst._zod.onattach.push((inst) => {
         const bag = inst._zod.bag;
         bag.minimum = def.size;
@@ -303,11 +306,12 @@ export const $ZodCheckSizeEquals = /*@__PURE__*/ core.$constructor("$ZodCheckSiz
     };
 });
 export const $ZodCheckMaxLength = /*@__PURE__*/ core.$constructor("$ZodCheckMaxLength", (inst, def) => {
+    var _a;
     $ZodCheck.init(inst, def);
-    inst._zod.when = (payload) => {
+    (_a = inst._zod.def).when ?? (_a.when = (payload) => {
         const val = payload.value;
         return !util.nullish(val) && val.length !== undefined;
-    };
+    });
     inst._zod.onattach.push((inst) => {
         const curr = (inst._zod.bag.maximum ?? Number.POSITIVE_INFINITY);
         if (def.maximum < curr)
@@ -331,11 +335,12 @@ export const $ZodCheckMaxLength = /*@__PURE__*/ core.$constructor("$ZodCheckMaxL
     };
 });
 export const $ZodCheckMinLength = /*@__PURE__*/ core.$constructor("$ZodCheckMinLength", (inst, def) => {
+    var _a;
     $ZodCheck.init(inst, def);
-    inst._zod.when = (payload) => {
+    (_a = inst._zod.def).when ?? (_a.when = (payload) => {
         const val = payload.value;
         return !util.nullish(val) && val.length !== undefined;
-    };
+    });
     inst._zod.onattach.push((inst) => {
         const curr = (inst._zod.bag.minimum ?? Number.NEGATIVE_INFINITY);
         if (def.minimum > curr)
@@ -359,11 +364,12 @@ export const $ZodCheckMinLength = /*@__PURE__*/ core.$constructor("$ZodCheckMinL
     };
 });
 export const $ZodCheckLengthEquals = /*@__PURE__*/ core.$constructor("$ZodCheckLengthEquals", (inst, def) => {
+    var _a;
     $ZodCheck.init(inst, def);
-    inst._zod.when = (payload) => {
+    (_a = inst._zod.def).when ?? (_a.when = (payload) => {
         const val = payload.value;
         return !util.nullish(val) && val.length !== undefined;
-    };
+    });
     inst._zod.onattach.push((inst) => {
         const bag = inst._zod.bag;
         bag.minimum = def.length;

package/v4/core/errors.cjs

@@ -48,6 +48,10 @@ const initializer = (inst, def) => {
         enumerable: true,
         // configurable: false,
     });
+    Object.defineProperty(inst, "toString", {
+        value: () => inst.message,
+        enumerable: false,
+    });
 };
 exports.$ZodError = (0, core_js_1.$constructor)("$ZodError", initializer);
 exports.$ZodRealError = (0, core_js_1.$constructor)("$ZodError", initializer, { Parent: Error });

package/v4/core/errors.js

@@ -17,6 +17,10 @@ const initializer = (inst, def) => {
         enumerable: true,
         // configurable: false,
     });
+    Object.defineProperty(inst, "toString", {
+        value: () => inst.message,
+        enumerable: false,
+    });
 };
 export const $ZodError = $constructor("$ZodError", initializer);
 export const $ZodRealError = $constructor("$ZodError", initializer, { Parent: Error });

package/v4/core/registries.cjs

@@ -6,7 +6,7 @@ exports.$output = Symbol("ZodOutput");
 exports.$input = Symbol("ZodInput");
 class $ZodRegistry {
     constructor() {
-        this._map = new WeakMap();
+        this._map = new Map();
         this._idmap = new Map();
     }
     add(schema, ..._meta) {
@@ -20,6 +20,11 @@ class $ZodRegistry {
         }
         return this;
     }
+    clear() {
+        this._map = new Map();
+        this._idmap = new Map();
+        return this;
+    }
     remove(schema) {
         const meta = this._map.get(schema);
         if (meta && typeof meta === "object" && "id" in meta) {

package/v4/core/registries.d.cts

@@ -13,9 +13,10 @@ type MetadataType = Record<string, unknown> | undefined;
 export declare class $ZodRegistry<Meta extends MetadataType = MetadataType, Schema extends $ZodType = $ZodType> {
     _meta: Meta;
     _schema: Schema;
-    _map: WeakMap<Schema, $replace<Meta, Schema>>;
+    _map: Map<Schema, $replace<Meta, Schema>>;
     _idmap: Map<string, Schema>;
     add<S extends Schema>(schema: S, ..._meta: undefined extends Meta ? [$replace<Meta, S>?] : [$replace<Meta, S>]): this;
+    clear(): this;
     remove(schema: Schema): this;
     get<S extends Schema>(schema: S): $replace<Meta, S> | undefined;
     has(schema: Schema): boolean;

package/v4/core/registries.d.ts

@@ -13,9 +13,10 @@ type MetadataType = Record<string, unknown> | undefined;
 export declare class $ZodRegistry<Meta extends MetadataType = MetadataType, Schema extends $ZodType = $ZodType> {
     _meta: Meta;
     _schema: Schema;
-    _map: WeakMap<Schema, $replace<Meta, Schema>>;
+    _map: Map<Schema, $replace<Meta, Schema>>;
     _idmap: Map<string, Schema>;
     add<S extends Schema>(schema: S, ..._meta: undefined extends Meta ? [$replace<Meta, S>?] : [$replace<Meta, S>]): this;
+    clear(): this;
     remove(schema: Schema): this;
     get<S extends Schema>(schema: S): $replace<Meta, S> | undefined;
     has(schema: Schema): boolean;

package/v4/core/registries.js

@@ -2,7 +2,7 @@ export const $output = Symbol("ZodOutput");
 export const $input = Symbol("ZodInput");
 export class $ZodRegistry {
     constructor() {
-        this._map = new WeakMap();
+        this._map = new Map();
         this._idmap = new Map();
     }
     add(schema, ..._meta) {
@@ -16,6 +16,11 @@ export class $ZodRegistry {
         }
         return this;
     }
+    clear() {
+        this._map = new Map();
+        this._idmap = new Map();
+        return this;
+    }
     remove(schema) {
         const meta = this._map.get(schema);
         if (meta && typeof meta === "object" && "id" in meta) {

package/v4/core/schemas.cjs

@@ -65,8 +65,8 @@ exports.$ZodType = 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;
                 }

package/v4/core/schemas.js

@@ -35,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;
                 }

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

@@ -536,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.
@@ -545,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: "#" };
@@ -564,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;
             }
@@ -580,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
@@ -606,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
@@ -671,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 ?? {};
@@ -681,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 {
@@ -712,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

@@ -39,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;
 }

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

@@ -39,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;
 }

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

@@ -532,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.
@@ -541,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: "#" };
@@ -560,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;
             }
@@ -576,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
@@ -602,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
@@ -667,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 ?? {};
@@ -677,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 {
@@ -707,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()) {