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.