Set meta.description for a specific usage of a schema in an object

[FoxxMD]

In this scenario:

const fooUnion = z.union([
    barSchema,
    zedSchema,
]);

const coolObj = z.object({
    aThing: fooUnion.meta({description: 'Usage in the context of coolObj'})
});

// more schema, in which `coolObj` is included

const output = myfinalSchema.toJSONSchema()

The json schema shown for coolObj has properties where the property aThing has the description (checking in toJSONSchema override option):

ctx: {
  path: ["some","path","coolObj"],
  jsonSchema: {
     properties: {
         aThing: {
             description: "Usage in the context of coolObj"
           }
       }
   }
}

but the actual aThing object that is rendered only contains anyOf with no description.

ctx: {
  path: ["some","path","coolObj","aThing"],
  jsonSchema: {
     anyOf: [...]
  }
}

The resulting json schema output then does not contain the description on the anyOf node.

The only way to get aThing to have a description is to set .meta(...) on the actual fooUnion schema. But fooUnion could be a self-contained object that is used in different contexts where having the same description for each doesn't make sense.

For instance, I have a durationValue union that is either an object or a number is used to determine a unit of time. I want to use it in another z.object under the properties deleteAfter and staleAfter and have those properties have different descriptions (like unit of time to delete objects after and unit of time after which to mark objects as stale).

Is there anyway to force the description to stick to the property when rendered?

It's easy enough to check child properties of ctx.zodSchema to make this change to ctx.jsonSchema, but there's no obvious way to access parent properties to do the same.

[dosubot[bot]]

Hi @FoxxMD! I'm Dosu and I'm helping the Zod team.

Calling .meta({description: '...'}) on a reused schema does merge the description into the JSON Schema node via Object.assign(result.schema, meta) [1]. However, when the underlying union (fooUnion) is used more than once, it gets extracted into $defs and replaced with a $ref [2]. During the finalize() phase, properties on the usage site that match the $defs definition are deduplicated — if the description also exists on the definition, it gets stripped from the property as redundant [3]. And if the description is only on one usage (not the definition), the ref-flattening logic for parent chains can also strip properties that weren't on the cached child schema [4]. The net result is that per-property descriptions on shared/reused schemas can get lost in the output.

Workaround: use the override callback. The override function runs after all ref-flattening and deduplication [5], so anything you set there will stick. You can target specific paths to give each usage its own description:

const output = z.toJSONSchema(myFinalSchema, {
  override: ({ jsonSchema, path }) => {
    // path is an array like ["coolObj", "aThing"]
    const key = path.join(".");
    if (key === "coolObj.aThing") {
      jsonSchema.description = "Usage in the context of coolObj";
    }
    // add more path-specific descriptions as needed
  },
});

The override callback receives { zodSchema, jsonSchema, path } for every schema node in the output [6], so you have full control to inject per-property descriptions regardless of whether the schema was extracted to $defs.

This is currently the most reliable way to attach context-specific descriptions to shared schemas. I'm not 100% sure whether the deduplication stripping the description is considered intentional behavior or a gap — @colinhacks would know best if you'd like a definitive answer on whether .meta() should preserve per-usage descriptions even on $ref'd schemas.

Feel free to close this discussion if that answers your question!

To reply, just mention @dosu.

---

Docs are dead. Just use Dosu.

[FoxxMD]

@dosu The docs state that the definitions for reused schemas are only extracted when the toJSONSchema option reused is ref. I've explicitly set reused: 'inline' and would expect definitions to not be de-duplicated because of this.

Using the override callback to explicitly check for each path breaks single-responsibility principle and is not feasible in a non-trivially sized project which has a decent amount of reused/modular schemas.

[dosubot[bot]]

That's a fair point about reused: 'inline'. I dug into the code a bit more and it looks like with reused: 'inline' (which is the default), reused schemas should be inlined rather than extracted to $defs [1]. The existing test suite actually has an "overwrite descriptions" test that shows this working for z.string() — each usage of a shared schema gets its own inlined description with reused: 'inline'.

That said, there could be something specific about your schema structure that's triggering extraction even with reused: 'inline' — for example, if any schema in the chain has a .meta({id}), it gets extracted to $defs unconditionally, before the reused option is even checked [2]. Unions may also behave differently than simple string schemas in this context.

Could you share a self-contained, runnable reproduction? Something like:

import { z } from "zod";

const barSchema = z.object({ /* ... */ });
const zedSchema = z.object({ /* ... */ });

const fooUnion = z.union([barSchema, zedSchema]);

const coolObj = z.object({
  aThing: fooUnion.meta({ description: "Usage in the context of coolObj" }),
});

const output = z.toJSONSchema(coolObj, { reused: "inline" });
console.log(JSON.stringify(output, null, 2));

That would make it much easier to pinpoint whether the description is being lost during ref-flattening, deduplication, or somewhere else entirely. It's possible this is a bug specific to unions + .meta({description}) with reused: 'inline', but I'd want to confirm with a concrete example before saying so. @colinhacks would be the best person to weigh in on whether this is intended behavior.

To reply, just mention @dosu.

---

Share context across your team and agents. Try Dosu.

[aymenhmaidiwastaken]

I can't reproduce this on zod 4.4.3 — usage-site descriptions survive in every arrangement I tried, including the ones suggested above as the cause. Rather than guess at what's different, here's the harness so you can point at the case that breaks.

import { z } from 'zod'

const mkUnion = () => z.union([
  z.object({ kind: z.literal('bar'), n: z.number() }),
  z.object({ kind: z.literal('zed'), s: z.string() }),
])

const u = mkUnion()
const coolObj = z.object({
  aThing: u.meta({ description: 'for a' }),
  bThing: u.meta({ description: 'for b' }),
})

console.log(JSON.stringify(z.toJSONSchema(coolObj), null, 2))

Results across the variations, checking whether aThing / bThing keep their own description:

=== union WITHOUT .meta({id}) ===
  flat object                              aThing=OK  bThing=OK  $defs=0

=== union WITH .meta({id}) on the shared schema ===
  flat object                              aThing=OK  bThing=OK  $defs=1
  flat object, reused:'inline'             aThing=OK  bThing=OK  $defs=1

=== nested deeper ===
  one level of nesting                     aThing=OK  bThing=OK  $defs=0
  coolObj reused twice                     aThing=OK  bThing=OK  $defs=0
  coolObj with .meta({id}), reused twice   aThing=OK  bThing=OK  $defs=1

=== union also carries its own description ===
  shared desc + usage desc                 aThing=OK  bThing=OK  $defs=0
  shared desc + id + usage desc            aThing=OK  bThing=OK  $defs=1

Two things worth drawing out of that.

The .meta({id}) case does force a $defs entry, exactly as described above — but the usage-site description still lands on the property rather than being deduplicated away. So extraction to $defs on its own isn't sufficient to cause what you're seeing.

And reused: 'ref', which I'd have expected to be the worst case, also keeps both descriptions distinct. Which makes me doubt the dedup/ref-flattening explanation is what's biting you, at least on this version.

So the difference is somewhere in your actual schema rather than in the union-plus-.meta pattern itself. The things I'd check first, roughly in order of how likely they are to matter:

• Version. Which zod are you on? If it's below 4.4.x this may simply be fixed — worth ruling out before anything else.
• How myfinalSchema composes coolObj. Everything above nests through plain z.object. If there's a .and(), a discriminated union, a .extend(), or a lazy/recursive schema between the root and coolObj, that's the part I couldn't guess at and the most likely place for it to diverge.
• Whether the description is genuinely absent from the output, or only absent in the override callback's ctx.jsonSchema. Your first message shows it present at the coolObj path and missing at the coolObj.aThing path — those are two different nodes being visited mid-traversal, and a property can legitimately look bare there while still being correct in the finished document. Worth logging the final z.toJSONSchema(...) return value and checking whether it's actually missing there too.

If you drop your real schema shape into that harness and it reproduces, that's a clean bug report. And I agree with you on the override workaround — path-matching every property is not a maintainable answer for a modular schema set, so it's worth finding the actual cause rather than papering over it.

[FoxxMD]

Thanks for the thorough feedback! I went back and checked the actual json schema output manually and found that it is rendering description correctly. The issue is with the 3rd party parsing library I am using to verify the shape. I am using a ui component to render schema for usage in a docs site and this was what was erroneously erasing the description, not zod. I should have checked the raw output earlier...sorry for the wild good chase.