Implement .clear() in . Fixes #4834

Author: colinhacks

packages/docs/content/json-schema.mdx

@@ -451,7 +451,7 @@ const jsonSchema = z.toJSONSchema(mySchema, { io: "input" });
 
 Passing a schema into `z.toJSONSchema()` will return a *self-contained* JSON Schema. 
 
-In other cases, you may have a set of Zod schemas you'd like to represent using multiple interlinked JSON Schemas, perhaps to write to `.json` files and serve from a web server. To achieve this, you can pass a [registry](/metadata#registries) into `z.toJSONSchema()`.
+In other cases, you may have a set of Zod schemas you'd like to represent using multiple interlinked JSON Schemas, perhaps to write to `.json` files and serve from a web server. 
 
 ```ts
 import * as z from "zod/v4";
@@ -475,7 +475,9 @@ z.globalRegistry.add(User, {id: "User"});
 z.globalRegistry.add(Post, {id: "Post"});
 ```
 
-The schemas above both have an `id` property registered in `z.globalRegistry`. To convert these to JSON Schema, pass the entire registry into `z.toJSONSchema()`.
+To achieve this, you can pass a [registry](/metadata#registries) into `z.toJSONSchema()`. 
+
+> **Important** — All schemas should have a registered `id` property in the registry! Any schemas without an `id` will be ignored. 
 
 ```ts
 z.toJSONSchema(z.globalRegistry);
@@ -506,9 +508,7 @@ z.toJSONSchema(z.globalRegistry);
 // }
 ```
 
-> Any schema with an `id` property in the registry will be extracted into `schemas`. 
-
-By default, the `$ref` URIs are relative paths like `"User"`. To make these absolute URIs, use the `uri` option. This expects a function that converts an `id` to a fully-qualified URI.
+By default, the `$ref` URIs are simple relative paths like `"User"`. To make these absolute URIs, use the `uri` option. This expects a function that converts an `id` to a fully-qualified URI.
 
 ```ts
 z.toJSONSchema(z.globalRegistry, {

packages/docs/content/metadata.mdx

@@ -28,6 +28,7 @@ myRegistry.add(mySchema, { description: "A cool schema!"});
 myRegistry.has(mySchema); // => true
 myRegistry.get(mySchema); // => { description: "A cool schema!" }
 myRegistry.remove(mySchema);
+myRegistry.clear(); // wipe registry
 ```
 
 TypeScript enforces that the metadata for each schema matches the registry's **metadata type**.
@@ -37,7 +38,7 @@ myRegistry.add(mySchema, { description: "A cool schema!" }); // ✅
 myRegistry.add(mySchema, { description: 123 }); // ❌
 ```
 
-> **Important** —  If you register metadata on a schema and include an `id` property, Zod will throw an error if multiple schemas share the same `id` value. Make sure all registered `id` values are unique per registry. This also applies to the global registry.
+> **Special handling for `id`** —  Zod registries treat the `id` property specially. An `Error` will be thrown if multiple schemas are registered with the same `id` value. This is true for all registries, including the global registry.
 
 
 ### `.register()`

packages/zod/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;
+      }>;
+    }>,
+  ]
+>;

packages/zod/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);
+});

packages/zod/src/v4/core/registries.ts

@@ -45,6 +45,12 @@ export class $ZodRegistry<Meta extends MetadataType = MetadataType, Schema exten
     return this as any;
   }
 
+  clear(): this {
+    this._map = new WeakMap();
+    this._idmap = new Map();
+    return this;
+  }
+
   remove(schema: Schema): this {
     this._map.delete(schema);
     return this;

packages/zod/src/v4/core/to-json-schema.ts

@@ -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,11 +627,13 @@ 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) };
+        if (externalId) {
+          return { ref: params.external.uri(externalId) };
+        }
 
         // otherwise, add to __shared
         const id: string = entry[1].defId ?? (entry[1].schema.id as string) ?? `schema${this.counter++}`;
-        entry[1].defId = id;
+        entry[1].defId = id; // set defId so it will be reused if needed
         return { defId: id, ref: `${params.external.uri("__shared")}#/${defsSegment}/${id}` };
       }
 

play.ts

@@ -2,43 +2,9 @@ import { z } from "zod/v4";
 
 z;
 
-// import * as z from "zod/v4";
+const a = z.string().meta({ id: "stuff" });
+const b = z.string().meta({ id: "stuff" });
+const obj = z.object({ a, b });
 
-export type SomeRecursiveUnion1 = z.ZodUnion<
-  [
-    z.ZodObject<{
-      foo: z.ZodReadonly<z.ZodPrefault<SomeRecursiveUnion1>>;
-    }>,
-  ]
->;
-
-// type Foo = z.core.$ZodRecord<z.ZodString, B>;
-// type B = z.ZodPipe<B, Foo>;
-
-const Category = z.object({
-  name: z.string(),
-  get subcategories() {
-    return z.array(z.union([z.string(), Category]));
-  },
-});
-
-const err = new z.core.$ZodError([
-  {
-    code: "invalid_type",
-    expected: "string",
-    path: [],
-    message: "Expected string, received number",
-    input: 1,
-  },
-]);
-console.log(err.toString());
-// But it works without `z.ZodReadonly` or without recursive reference:
-
-// export type SomeRecursiveUnion2 = z.ZodUnion<
-//   [
-//     z.ZodObject<{
-//       foo: z.ZodRecord<z.ZodString, SomeRecursiveUnion2>;
-//       bar: z.ZodReadonly<z.ZodRecord<z.ZodString, z.ZodString>>;
-//     }>,
-//   ]
-// >;
+const json = z.toJSONSchema(obj);
+console.log(json);