The alternatives a value may be drawn from
ReadonlykindDiscriminator identifying this as a union shape.
Inheritance — cannot be overridden.
ReadonlybranchesThe alternatives a value may be drawn from.
Stated flat: a branch that is itself a union is replaced, as the shape is built, by the alternatives it holds, so that a caller routing a value walks one list however the union was assembled. A branch left deferred is flattened where it is resolved rather than where it is stated.
Inheritance — each child branch narrows exactly one parent branch; unpaired parent branches are dropped.
Describes a value drawn from one of several alternatives.
Admits whatever any of its branches admits, so that a property whose vocabulary ranges over unrelated types (a plain string or any of several structured resources, say) is described by a single shape. A branch is a shape in its own right, a union included, possibly deferred to break definition cycles.
Matching
Which branches an operation is carried out against is decided by the input the caller supplies, under the regime that input belongs to:
kindand, where branches share it, their lexicalpattern), as a bound filters by order and need not be a legal value of the branch it selects. A localised branch takes a plain string bound, and links and embedded resources take none;kindalone and ignores any lexicalpattern, as an option is tested by equality and an option outside the domain is a legal filter matching nothing. A localised branch takes a plain string option or a map of options keyed by language tag;An input matching no branch is rejected as unsatisfiable, and one required to single out a branch but matching several is rejected as ambiguous. A text search singles out no branch at all: it filters every textual branch at once.
Branches are expected to be disjoint: no legal value satisfies two of them at once. Disjointness is a modelling contract rather than a property proved as the shape is built, so overlapping branches are accepted and an offending value is rejected only when it is matched. A union filtered by relational bounds is held to a stricter grade, as a bound is told apart by syntax alone: it admits at most one numeric and one boolean branch, and string branches only under mutually exclusive patterns. One filtered by set-matching options is held to a stricter grade still, as an option is told apart by kind alone: it admits at most one branch of each kind. Under either grade, a plain string over a string branch and a localised one is ambiguous.
Branches describing or linking to resources are expected to be coherent: a member name several of them declare denotes the same property throughout the union, agreeing on its kind, its
forwardandreversepredicates and itscaptiveandforeignflags, while its range, cardinality and value domain may differ. Branches may be deferred, so coherence is checked as the branches are first resolved rather than as the union is built, and an incoherent union is rejected there.Inheritance
Where a resource!ResourceShape extends the shapes it lists as
parents, union-valued members are merged according to the following rules. The child is the extending shape; the parent is the inherited one.kindbranchesA child narrowing a branch that no parent branch matches, one that several match, or one already taken by another child branch is reported as an error. A child declaring a single non-union shape narrows the one parent branch it matches and collapses the member to that shape, leaving the value no longer polymorphic.
See