Validation Request: Enforce refs in OpenAPI Discriminated Unions

[kennyjwilli]

Issue Description

When using discriminated unions with OpenAPI, the specification requires all union members to use $ref references when a discriminator field is present. However, zod-openapi currently generates OpenAPI specs even when some union members lack the required .openapi({ ref: ... }) configuration, resulting in a spec without the discriminator property.

Current Behavior

Consider this example:

const apple = z.object({
  type: z.literal('apple'),
  color: z.string(),
});

const orange = z
  .object({
    type: z.literal('orange'),
    diameter: z.number(),
  })
  .openapi({ ref: 'Orange' });

const data = z.discriminatedUnion('type', [apple, orange]);

This generates an OpenAPI spec without the discriminator property because the apple schema lacks a ref:

{
  "oneOf": [
    {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "const": "apple"
        },
        "color": {
          "type": "string"
        }
      },
      "required": [
        "type",
        "color"
      ]
    },
    {
      "$ref": "#/components/schemas/Orange"
    }
  ]
}

Desired Behavior

I propose adding validation to throw an error when generating OpenAPI specs for discriminated unions where any member lacks a ref. This would help prevent the common mistake of adding a new union member without the required .openapi({ ref: ... }) configuration.

The discriminator property works correctly when all members have refs:

const apple = z.object({
  type: z.literal('apple'),
  color: z.string(),
}).openapi({ ref: 'Apple' });  // Added ref

const orange = z.object({
  type: z.literal('orange'),
  diameter: z.number(),
}).openapi({ ref: 'Orange' });

const data = z.discriminatedUnion('type', [apple, orange]);

Question

Is it possible to add this validation to zod-openapi? This would help ensure generated OpenAPI specs correctly implement discriminated unions according to the specification.

[samchungy]

I'm open to making it an option eg. https://github.com/samchungy/zod-openapi#createdocumentoptions but I don't think I want to throw an error by default as Zod discriminated unions can accept more permutations than JSON Schema/OpenAPI is compatible with

[kennyjwilli]

Seems reasonable.

[samchungy]

4.1.0

https://github.com/samchungy/zod-openapi/releases/tag/v4.1.0

[kennyjwilli]

Excellent. Thank you @samchungy.

[kennyjwilli]

Works great.

[yjp20]

Where are you seeing that all union members must be a $ref? This does seem to be consistent with the examples but not explicitly said anywhere, nor in the 3.1 docs.

If this isn't true, it would be better to emit the discriminator: { propertyName: '...' } even when one of the component schemas aren't a RefObject.

[samchungy]

You're right! Look like we can get away with just the propertyName. That sounds like a good fallback if we can't generate a mapping