ADR 0267 — A flat alternative names the values that select it

Invariants: I1, I2. Amends ADR 0205.

Context

ADR 0205 keeps the distinct shapes of a field the variants share as an anyOf, ordered canonically so that one union reads the same however its variants are listed, and leaves the discriminator-to-field correlation out of the presentation. For a union whose variants differ only by such a field — { type, data } with a different data per type — that leaves a model the discriminator as an enum and a set of shapes, and nothing that pairs them: it is told type: text | image | quiz and three shapes for data, and it guesses.

Decision

Each alternative of the joined field carries description: "When <discriminator> = <values>.", naming every discriminator value whose variant has that shape (photo | video for a shape two values share). The correlation is text: it adds no oneOf, no conditional keyword and no vendor keyword, so the schema stays inside the one profile every provider is served (ADR 0047) and validates exactly the same values. The canonical order of the alternatives is unchanged.

Consequences

A model reading a flattened tool can pair each shape with its value. The structural alternatives of ADR 0205 gain a description each; a test comparing the exact flattened shape lists it (tests/flatten-structural.test.ts, tests/flatten-collision.test.ts, tests/collided-field-keeps-type.test.ts), and tests/flatten-alternative-labels.test.ts proves the labels, including one shape shared by two values. Validation is unaffected: the original Zod schema still owns parsing.