toJSONSchema with references & draft-7 results in allOf usage, breaking AI structured output.

[DJWassink]

Hello, I am using Zod to generate a json_schema. Sadly the schema got a bit too large and some AI models started outputing gibberish.
To resolve this I tried to enable the reused flag with the value "ref". This has been working perfect aside from one little issue.

If you have a shared schema (thus one that will be referenced) and apply something extra to this like a .nullable(). It will create an allOf condition which results in GPT throwing an error since this condition isn't supported in its json_schema subset.
Is this by design since draft-7 can't have properties in the same object as the reference?
And if so, is there an elegant way to make it somehow work?
For the fields that have this issue we for now don't add any modifiers to the properties or inline some schema, but this result in having duplicate definition.

import { z } from "zod";

const aBool = z.boolean();
const schema = z.strictObject({
  foo: aBool,
  bar: aBool.describe("somehow this becomes an allOf"),
});

console.log(
  JSON.stringify(
    z.toJSONSchema(schema, {
      target: "draft-7",
      reused: "ref",
    }),
    null,
    2
  )
);

Output which has an allOf condition that breaks GPT:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "foo": {
      "$ref": "#/definitions/__schema0"
    },
    "bar": {
      "description": "somehow this becomes an allOf",
      "allOf": [
        {
          "$ref": "#/definitions/__schema0"
        }
      ]
    }
  },
  "required": [
    "foo",
    "bar"
  ],
  "additionalProperties": false,
  "definitions": {
    "__schema0": {
      "type": "boolean"
    }
  }
}

[dosubot[bot]]

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

This is by design and is required by the JSON Schema draft-7 spec: you can't have a $ref and other properties (like description or nullable) in the same schema object, so Zod wraps the $ref in an allOf to attach those modifiers. This is the only way to express "a reference, plus some extra metadata" in draft-7 and similar targets. You can see this logic in Zod's implementation and in related discussions with the maintainers [source].

There isn't a built-in way in Zod to avoid allOf in this scenario for draft-7. Your options are:

• Use reused: "inline" to inline schemas (no $ref, but more duplication).
• Avoid attaching modifiers like .describe() or .nullable() to reused schemas.
• Target a newer draft (like draft-2020-12), which allows $ref with sibling properties.
• Post-process the generated schema to flatten or remove allOf (though this can be tricky and may not always be lossless).

If you need to support AI models that don't handle allOf, the most robust approach is to avoid modifiers on reused schemas or keep everything inline. More details and workarounds are discussed in the docs and issues:

• Zod JSON Schema docs
• Issue #5103
• Relevant code

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}

   

[DJWassink]

So basically GPT doesnt support any draft higher then 7 (draft-2020-12 does indeed support this case).
Sadly draft-7 doesn't support setting a $ref with other properties (see

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

Line 387 in 9977fb0

// older drafts can't combine $ref with other properties

)

For now we are planning to use factory functions to create new duplicate schemas on the fly if they need modifiers.
Something like this:

const aBool = () => z.boolean();
const cachedABool = aBool();
const schema = z.strictObject({
  foo: cachedABool,
  bar: aBool().describe("somehow this becomes an allOf?"),
});

[sunnypatell]

this is a known limitation stemming from how JSON Schema draft-7 handles $ref. you're on the right track with your analysis.

why allOf appears

in draft-7 (and draft-04), a $ref keyword "consumes" the entire schema object -- any sibling keywords next to $ref are ignored. so when you do aBool.describe("..."), zod needs to attach a description alongside a $ref, and the only spec-compliant way to do that in draft-7 is wrapping the $ref inside an allOf:

{
  "description": "somehow this becomes an allOf",
  "allOf": [{ "$ref": "#/definitions/__schema0" }]
}

this is the exact logic in zod's source:

if (refSchema.$ref && (ctx.target === "draft-07" || ctx.target === "draft-04" || ctx.target === "openapi-3.0")) {
  // older drafts can't combine $ref with other properties
  schema.allOf = schema.allOf ?? [];
  schema.allOf.push(refSchema);
}

for draft-2020-12, it just merges $ref alongside sibling properties directly (which is valid in that draft), so no allOf wrapper.

the problem with OpenAI

OpenAI's structured output only supports a subset of JSON Schema. allOf is not in that subset. however, $ref, $defs, and anyOf are supported. so you just need to avoid the allOf wrapper.

workarounds

1. use target: "draft-2020-12" (recommended)

since draft-2020-12 is zod's default and allows $ref with sibling properties, the allOf wrapper isn't generated at all. OpenAI doesn't strictly enforce a draft version and does support $defs (the draft-2020-12 equivalent of definitions).

const result = z.toJSONSchema(schema, {
  target: "draft-2020-12",
  reused: "ref",
});

output will look like:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "foo": { "$ref": "#/$defs/__schema0" },
    "bar": {
      "$ref": "#/$defs/__schema0",
      "description": "somehow this becomes an allOf"
    }
  },
  "required": ["foo", "bar"],
  "additionalProperties": false,
  "$defs": {
    "__schema0": { "type": "boolean" }
  }
}

no allOf, $ref sits alongside description as a sibling. you may want to strip the $schema field before sending to OpenAI since they might not expect it -- just delete result.$schema.

2. use the override callback to flatten allOf

if you really need to stick with draft-7 for other reasons, you can post-process the schema using zod's override option to unwrap simple allOf cases:

const result = z.toJSONSchema(schema, {
  target: "draft-7",
  reused: "ref",
  override: ({ jsonSchema }) => {
    // flatten single-element allOf that only wraps a $ref
    if (
      jsonSchema.allOf &&
      Array.isArray(jsonSchema.allOf) &&
      jsonSchema.allOf.length === 1 &&
      jsonSchema.allOf[0].$ref
    ) {
      jsonSchema.$ref = jsonSchema.allOf[0].$ref;
      delete jsonSchema.allOf;
    }
  },
});

this turns { "description": "...", "allOf": [{"$ref": "..."}] } into { "description": "...", "$ref": "..." }. technically not valid draft-7, but OpenAI doesn't validate against draft-7 strictly and does support $ref, so it works in practice.

note: there's a known issue (#5103) where override doesn't get called for every instance of a reused schema when it has different modifiers. if you hit that, the draft-2020-12 approach is more reliable.

3. factory functions (what you're already doing)

your current approach of creating new schema instances for modified versions is valid and avoids the reuse detection entirely:

const aBool = () => z.boolean();
const cachedABool = aBool();

const schema = z.strictObject({
  foo: cachedABool,
  bar: aBool().describe("no allOf since it's a unique schema instance"),
});

this works because zod tracks reuse by reference identity. a fresh z.boolean() call returns a new instance that won't be ref'd. downside is you lose the deduplication benefit of reused: "ref" for those specific fields.

4. selective inlining with override

if most of your schema benefits from reused: "ref" but only a few fields have modifiers causing allOf, you could selectively inline just those by removing the $ref in the override:

override: ({ jsonSchema, zodSchema }) => {
  // if this schema has allOf wrapping a $ref, inline the definition instead
  if (jsonSchema.allOf?.length === 1 && jsonSchema.allOf[0].$ref) {
    // replace with the actual type inline
    delete jsonSchema.allOf;
    // reconstruct the type from the zod schema
    const def = zodSchema._zod.def;
    if (def.type === "boolean") jsonSchema.type = "boolean";
    // extend for other types as needed
  }
},

tldr

the cleanest fix is switching to target: "draft-2020-12" (or just omitting target since it's the default). it avoids allOf entirely and OpenAI supports both $ref and $defs which are what draft-2020-12 generates. just strip the $schema property before sending it to the API if needed.

relevant links:

• zod JSON Schema docs
• source code for the allOf logic
• OpenAI structured output supported schemas
• Azure docs with explicit supported/unsupported feature list

[wesleysmyth]

Yes, this is by design in JSON Schema draft-7. In draft-7, $ref must be the only keyword in an object — you can't put description, nullable, or any other property alongside it. So when Zod needs to add a description to a $ref, it wraps it in allOf:

{
  "description": "somehow this becomes an allOf",
  "allOf": [{ "$ref": "#/definitions/__schema0" }]
}

This is valid draft-7, but OpenAI's structured output subset doesn't support allOf.

Fix 1: Use draft-2020-12 instead of draft-7

JSON Schema 2020-12 allows properties alongside $ref, so Zod can emit:

{
  "$ref": "#/$defs/__schema0",
  "description": "somehow this becomes an allOf"
}

const schema = z.toJSONSchema(mySchema, {
  target: "draft-2020-12",
  reused: "ref",
});

However, OpenAI may not fully support draft-2020-12 features either. Test this with your specific model.

Fix 2: Post-process to inline allOf with single refs

Strip the allOf wrapper when it only contains a single $ref:

function flattenSingleAllOf(schema: any): any {
  if (typeof schema !== "object" || schema === null) return schema;

  if (Array.isArray(schema)) {
    return schema.map(flattenSingleAllOf);
  }

  const result: any = {};
  for (const [key, value] of Object.entries(schema)) {
    result[key] = flattenSingleAllOf(value);
  }

  // Flatten: { allOf: [{ $ref: "..." }], description: "..." }
  // Into:   { $ref: "...", description: "..." }
  if (
    result.allOf &&
    Array.isArray(result.allOf) &&
    result.allOf.length === 1 &&
    result.allOf[0].$ref
  ) {
    const { allOf, ...rest } = result;
    return { ...allOf[0], ...rest };
  }

  return result;
}

// Usage
const raw = z.toJSONSchema(mySchema, { target: "draft-7", reused: "ref" });
const cleaned = flattenSingleAllOf(raw);

Fix 3: Inline refs entirely (no $ref at all)

If OpenAI also chokes on $ref, use reused: "inline" to skip refs altogether:

const schema = z.toJSONSchema(mySchema, {
  target: "draft-7",
  reused: "inline", // Duplicate definitions instead of using $ref
});

This produces a larger schema (duplicated definitions), but it's fully self-contained with no $ref or allOf. The trade-off is schema size — which was your original problem.

Fix 4: Hybrid — inline small schemas, ref large ones

If only certain shared schemas trigger the allOf issue (the ones with .describe() or .nullable()), you can selectively remove the modifier:

// Instead of:
const aBool = z.boolean();
const schema = z.strictObject({
  foo: aBool,
  bar: aBool.describe("a described boolean"), // triggers allOf
});

// Use a fresh schema for described fields:
const schema = z.strictObject({
  foo: aBool,
  bar: z.boolean().describe("a described boolean"), // Not reused, no $ref needed
});

This keeps $ref for the unmodified shared schemas and inlines the ones that would need allOf.

Recommended approach for OpenAI

The most reliable path for OpenAI structured output:

const schema = z.toJSONSchema(mySchema, {
  target: "draft-7",
  reused: "inline", // Safest for AI models
});

If the schema is too large with inline, use reused: "ref" + the flattenSingleAllOf post-processor above.