toJSONSchema makes optional fields with default required

[px-d]

Hey Zod Community,

I use toJSONSchema on an object that defines an optional number and a default value for said number. The generated JSON Schema marks the number as required though, is this intended?

.catch() generates a default value and the field is not required.

Quick example:

const schema = z.object({
  n1: z.number().optional().default(1), // Marked as required with default
  n2: z.number().optional().catch(1), // Optional with default
});

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "n1": {
      "default": 1,
      "type": "number"
    },
    "n2": {
      "default": 1,
      "type": "number"
    }
  },
  "required": [
    "n1"
  ],
  "additionalProperties": false
}

Semantically, I’d expect optional().default() to provide a default value without making the field required, similar to .catch().

What’s the intended behavior here?

Thanks for taking the time!

[dosubot[bot]]

Hi @px-d! I'm Dosu and I’m helping the zod team.

This is intentional and matches how Zod interprets .default() and .catch() when generating JSON Schema. When you use .default(), Zod treats the field as required in the schema output because the default is applied at parse time, so the field is always present in the output—even if it was missing from the input. In contrast, .catch() is a fallback for validation errors and does not affect whether the field is required in the schema; it only provides a value if parsing fails, so the field remains optional in the JSON Schema output.

If you want the field to remain optional in the generated JSON Schema while still having a default, you can pass { io: 'input' } as the second argument to toJSONSchema:

z.toJSONSchema(schema, { io: 'input' });

This preserves the optional status of fields with defaults in the schema output. More details and discussion can be found in this issue and this comment.

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}