Add descriptions to schemas for conversion to JSON Schema

[flekschas]

I'm excited about the newly added toJSONSchema() function to turn a Zod schema into a JSON schema. One critical feature I'm wondering about is whether it's possible to add descriptions to the Zod schema such that they show up in the converted JSON schema.

For example, I'd love to do the following

import { z } from "zod";
 
const Person = z.object({
  name: z.string().describe('The name of the person'),
  age: z.number().describe('The age in milliseconds since year 1337'),
});
 
z.toJSONSchema(schema)
// => {
//   type: 'object',
//   properties: {
//     name: { type: 'string', description: 'The name of the person' },
//     age: { type: 'number', description: 'The age in milliseconds since year 1337' }
//   },
//   required: [ 'name', 'age' ],
//   additionalProperties: false,
// }

Is this at all possible right now?

[dosubot[bot]]

Hi @flekschas! I'm Dosu and I’m helping the zod team.

Yes, this is fully supported in Zod v4. Descriptions you add with .describe() (or with .meta({ description: ... })) are included in the output of toJSONSchema(). Your example will work as expected, and the descriptions will appear in the generated JSON Schema under each property.

For more complex metadata (like title, examples, etc.), use .meta(), but for simple descriptions, .describe() is fine. Here’s an example from the docs:

const mySchema = z.object({
  firstName: z.string().describe("Your first name"),
  lastName: z.string().meta({ title: "last_name" }),
  age: z.number().meta({ examples: [12, 99] }),
});

z.toJSONSchema(mySchema);
// => {
//   type: 'object',
//   properties: {
//     firstName: { type: 'string', description: 'Your first name' },
//     lastName: { type: 'string', title: 'last_name' },
//     age: { type: 'number', examples: [12, 99] }
//   },
//   required: [ 'firstName', 'lastName', 'age' ]
// }

You can find more details in the metadata docs and the JSON Schema conversion section. If this answers your question, feel free to close the issue!

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}   

[flekschas]

Oh boy, I just found it too 🤦‍♂️ Sorry for the noise.