XI · Structure & DataMature★★

Polymorphic Record

also known as Tagged Union, Discriminated Union

Represent a family of related entities in a single core schema with type-specific extensions.

Context

A team is designing a data model for a family of related entities that share most of their fields but differ in a few. A textile catalogue has yarn, fabric, and trim records, each with a common core (a stock-keeping unit, a supplier, a lead time) plus a handful of type-specific fields (yarn weight, fabric weave, trim attachment). A user-content system has projects, queues, and favourites that share an owner and a timestamp but diverge in their payloads. The team has to decide how to represent the shared core and the divergent extensions in a single schema that clients of different ages can still read.

Problem

Two naive choices both go wrong. One schema per sub-type duplicates the common fields and forces every client to know about every sub-type; when a new sub-type appears, old clients break or have to be updated in lockstep. A single flat schema that contains every possible field for every sub-type is bloated, hard to validate, and silently allows nonsensical combinations such as a fabric record carrying a yarn weight. The team needs a representation that keeps the common parts common, isolates the per-sub-type fields, and lets old clients survive the addition of a new sub-type.

Forces

  • Common fields must stay common; new sub-types must not break old ones.
  • Type-specific fields need a clean place to live.
  • Validation must be per-sub-type, not just per-record.

Example

A textile-trading platform has yarn, fabric, and trim records, each with shared fields (sku, supplier, lead-time) plus type-specific ones (yarn count, fabric weave, trim attachment). Three separate schemas duplicate code; one bloated 'material' schema with every field is unenforceable. The team adopts a polymorphic-record: a core schema with the shared fields and a `material_type` discriminator, plus namespaced extension blocks (yarn:{}, fabric:{}, trim:{}). Clients that don't understand a sub-type still read the core fields and round-trip the rest losslessly.

Diagram

Solution

Therefore:

Define a core schema with the common fields and a discriminator (e.g. `material_type`). Sub-type fields live in a namespaced extension block (e.g. `yarn: {...}` for yarn-specific). Clients that do not understand a sub-type still read the core fields and round-trip the rest without data loss.

What this pattern forbids. Sub-type fields must live under their namespaced extension; they cannot pollute the core.

And the patterns that stand alongside it, or against it —

  • complementsSchema Extensibility★★— Build schemas that evolve without breaking old clients via reserved namespaces and extension blocks.
  • complementsTranslation Layer★★— Insert a typed boundary between the agent's clean domain model and a messy or legacy external API.

Neighbourhood

Click any neighbour to follow the language. Scroll to zoom, drag to pan.

References

Provenance