fix: apply description and default metadata to enum, const, and not schemas in fromJSONSchema (#5758)

* fix: apply description and default to enum, const, and not schemas in fromJSONSchema

Fixes #5732

Early returns for enum, const, and not: {} (never) schemas in
convertBaseSchema() bypassed the metadata application block at the end
of the function.

Extract metadata application into a helper function applyBaseMetadata()
and call it from each of the affected early-return paths so that
description and default are consistently honored across all schema types.

* refactor: consolidate annotation metadata application in convertSchema

Move `description` and `default` handling out of `convertBaseSchema` and
into a single application site at the end of `convertSchema`, after
composition keywords (anyOf/oneOf/allOf) and wrappers (nullable/readOnly)
have been applied.

This eliminates the original bug class — early returns in
`convertBaseSchema` for `enum`, `const`, and `not: {}` silently dropped
description/default — without needing per-branch helper calls. As a
side effect it also fixes the same latent bug for the `type: [...]`
array expansion path.

Apply order is `default` → extraMeta → `describe`, so the `.describe()`
clone sits at the top of the parent chain. `_zod.parent` inheritance in
`$ZodRegistry.get()` then keeps `extraMeta` reachable from the returned
reference, while `schema.description` continues to resolve via
globalRegistry as before.

Adds tests for description/default on `type: [...]` arrays and for the
description+default+anyOf composition cases.

---------

Co-authored-by: Colin McDonnell <[email protected]>

Author: mibragimov

packages/zod/src/v4/classic/from-json-schema.ts

@@ -527,14 +527,6 @@ function convertBaseSchema(schema: JSONSchema.JSONSchema, ctx: ConversionContext
       throw new Error(`Unsupported type: ${type}`);
   }
 
-  // Apply metadata
-  if (schema.description) {
-    zodSchema = zodSchema.describe(schema.description);
-  }
-  if (schema.default !== undefined) {
-    zodSchema = zodSchema.default(schema.default);
-  }
-
   return zodSchema;
 }
 
@@ -586,26 +578,32 @@ function convertSchema(schema: JSONSchema.JSONSchema | boolean, ctx: ConversionC
     baseSchema = z.readonly(baseSchema);
   }
 
-  // Collect metadata: core schema keywords and unrecognized keys
+  // Apply `default` so it wraps the fully-composed schema. This ensures
+  // `parse(undefined) -> default` works regardless of which branch of
+  // `convertBaseSchema` produced the inner schema (enum/const/not/typed/etc.).
+  if (schema.default !== undefined) {
+    baseSchema = baseSchema.default(schema.default);
+  }
+
+  // Collect non-description annotation metadata into the user-supplied
+  // registry. Description is handled separately below via `.describe()` to
+  // preserve the contract that `schema.description` reads from globalRegistry.
   const extraMeta: Record<string, unknown> = {};
 
-  // Core schema keywords that should be captured as metadata
   const coreMetadataKeys = ["$id", "id", "$comment", "$anchor", "$vocabulary", "$dynamicRef", "$dynamicAnchor"];
   for (const key of coreMetadataKeys) {
     if (key in schema) {
       extraMeta[key] = schema[key];
     }
   }
 
-  // Content keywords - store as metadata
   const contentMetadataKeys = ["contentEncoding", "contentMediaType", "contentSchema"];
   for (const key of contentMetadataKeys) {
     if (key in schema) {
       extraMeta[key] = schema[key];
     }
   }
 
-  // Unrecognized keys (custom metadata)
   for (const key of Object.keys(schema)) {
     if (!RECOGNIZED_KEYS.has(key)) {
       extraMeta[key] = schema[key];
@@ -616,6 +614,13 @@ function convertSchema(schema: JSONSchema.JSONSchema | boolean, ctx: ConversionC
     ctx.registry.add(baseSchema, extraMeta);
   }
 
+  // Apply description last. `.describe()` clones the schema and sets
+  // `_zod.parent` on the clone, so registry lookups on the returned reference
+  // still resolve `extraMeta` via parent inheritance.
+  if (schema.description) {
+    baseSchema = baseSchema.describe(schema.description);
+  }
+
   return baseSchema;
 }
 

packages/zod/src/v4/classic/tests/from-json-schema.test.ts

@@ -732,3 +732,110 @@ test("contentEncoding and contentMediaType are stored as metadata", () => {
   expect(meta?.contentEncoding).toBe("base64");
   expect(meta?.contentMediaType).toBe("image/png");
 });
+
+test("description on enum schema is applied", () => {
+  const schema = fromJSONSchema({
+    enum: ["red", "green", "blue"],
+    description: "A color value",
+  });
+  expect(schema.description).toBe("A color value");
+  expect(schema.parse("red")).toBe("red");
+});
+
+test("description on const schema is applied", () => {
+  const schema = fromJSONSchema({
+    const: "hello",
+    description: "A greeting",
+  });
+  expect(schema.description).toBe("A greeting");
+  expect(schema.parse("hello")).toBe("hello");
+});
+
+test("description on not: {} (never) schema is applied", () => {
+  const schema = fromJSONSchema({
+    not: {},
+    description: "A never schema",
+  });
+  expect(schema.description).toBe("A never schema");
+  expect(() => schema.parse("anything")).toThrow();
+});
+
+test("default on enum schema is applied", () => {
+  const schema = fromJSONSchema({
+    enum: ["red", "green", "blue"],
+    default: "red",
+  });
+  expect(schema.parse(undefined)).toBe("red");
+});
+
+test("default on const schema is applied", () => {
+  const schema = fromJSONSchema({
+    const: "hello",
+    default: "hello",
+  });
+  expect(schema.parse(undefined)).toBe("hello");
+});
+
+test("description and default on enum schema are both applied", () => {
+  const schema = fromJSONSchema({
+    enum: ["red", "green", "blue"],
+    description: "A color value",
+    default: "red",
+  });
+  expect(schema.description).toBe("A color value");
+  expect(schema.parse(undefined)).toBe("red");
+  expect(schema.parse("green")).toBe("green");
+});
+
+test("description on type-array schema is applied", () => {
+  const schema = fromJSONSchema({
+    type: ["string", "number"],
+    description: "A string or number",
+  } as any);
+  expect(schema.description).toBe("A string or number");
+  expect(schema.parse("hello")).toBe("hello");
+  expect(schema.parse(42)).toBe(42);
+});
+
+test("default on type-array schema is applied", () => {
+  const schema = fromJSONSchema({
+    type: ["string", "number"],
+    default: "fallback",
+  } as any);
+  expect(schema.parse(undefined)).toBe("fallback");
+  expect(schema.parse("hello")).toBe("hello");
+  expect(schema.parse(42)).toBe(42);
+});
+
+test("description on schema with anyOf is applied to the outer schema", () => {
+  const schema = fromJSONSchema({
+    description: "Either a string or a number",
+    anyOf: [{ type: "string" }, { type: "number" }],
+  });
+  expect(schema.description).toBe("Either a string or a number");
+  expect(schema.parse("hello")).toBe("hello");
+  expect(schema.parse(42)).toBe(42);
+});
+
+test("default on schema with anyOf is applied to the outer schema", () => {
+  const schema = fromJSONSchema({
+    default: "fallback",
+    anyOf: [{ type: "string" }, { type: "number" }],
+  });
+  expect(schema.parse(undefined)).toBe("fallback");
+  expect(schema.parse(42)).toBe(42);
+});
+
+test("description and unrecognized metadata coexist on the same schema", () => {
+  const customRegistry = z.registry<{ "x-custom"?: string; description?: string }>();
+  const schema = fromJSONSchema(
+    {
+      type: "string",
+      description: "A custom string",
+      "x-custom": "value",
+    },
+    { registry: customRegistry }
+  );
+  expect(schema.description).toBe("A custom string");
+  expect(customRegistry.get(schema)?.["x-custom"]).toBe("value");
+});