The Truck Doesn't Care What's Inside: Schema Flexibility and Polymorphic Documents

Opening Scene

A moving truck carries lamps, bookshelves, and kitchen appliances side by side, none of them sharing a common shape, size, or set of parts, and the truck doesn’t need them to. Each item is packed appropriately for what it actually is, and the truck simply carries the collection of genuinely different things together toward the same destination. A shelving system demanding every item conform to identical compartments could never accommodate this natural variety in the first place.

Polymorphic documents in a collection embrace this exact same natural variety.

In Plain English

A polymorphic document collection holds documents that represent genuinely different kinds, or variants, of a related concept, each with its own appropriate structure, within the same collection. A collection of “products,” for instance, might hold both physical items with weight and dimensions and digital items with a file size and license terms — genuinely different shapes, coexisting naturally in one collection because the underlying concept, “product,” legitimately varies in kind.

The Old Way

Handling genuine variation well, without either over-generalizing into a vague, unhelpful structure or awkwardly forcing every variant into an identical shape, has always required real design judgment:

• A discriminator field — a “type” or “kind” attribute — is the classic pattern for making a polymorphic collection’s variety explicit and queryable, letting an application or query correctly interpret each document’s structure based on its declared type.
• Genuine polymorphism differs from simple missing data: a physical product genuinely lacking a “file size” field is structurally different from a digital product’s file size being accidentally left blank, and a well-designed polymorphic schema makes this distinction clear through its discriminator, not ambiguous.
• Overusing polymorphism to avoid genuine schema design discipline is a real risk — cramming genuinely unrelated concepts into one collection just because the database technically allows it tends to produce a confusing, poorly-organized model, not a genuinely flexible one.

Getting this right has always meant using polymorphism specifically for genuine, legitimate variation within a coherent concept, with a clear discriminator making that variation explicit, rather than as an excuse to skip real design thinking.

What’s Changing (and Why AI Is the Reason)

1. AI-assisted variant detection can analyze a collection’s actual documents and identify genuine, recurring structural variants, informing whether a collection is legitimately polymorphic or has simply accumulated inconsistent, undisciplined structure over time. Rather than a modeler manually reviewing samples to distinguish genuine variants from accidental inconsistency, AI-assisted clustering of a collection’s actual document shapes can reveal real, coherent variant groups worth formalizing with a discriminator.
2. AI agents querying a polymorphic collection need to correctly understand each document’s variant to interpret its fields correctly, making clear discriminator conventions genuinely important for reliable agent-generated queries. An agent unaware of a collection’s polymorphic structure might incorrectly assume every document shares the same fields, producing queries that fail or silently misinterpret data for certain variants.
3. AI-assisted schema documentation can automatically catalog a polymorphic collection’s actual variants and their distinct structures, closing a gap where this crucial context often exists only informally, if at all, in application code. This gives both human developers and AI agents a genuinely reliable reference for a collection’s real, full range of legitimate document shapes.

The Metaphor, Fully Extended

Moving Company Element	Polymorphic Document Concept
A truck carrying lamps, bookshelves, and kitchen appliances side by side, each packed appropriately	A polymorphic collection, holding genuinely different document variants within one collection
A shipping label marking each item’s category — furniture, electronics, kitchenware — for the unloading crew	A discriminator field, making a document’s variant explicit and queryable
A kitchen appliance genuinely having no shelving dimensions, versus a bookshelf’s dimensions being accidentally left blank	Genuine polymorphic variation, distinct from simple missing or incomplete data
A crew cramming genuinely unrelated items into one truck just because there happened to be room	Overusing polymorphism to avoid genuine schema design discipline
A logistics analyst reviewing years of shipments to identify the real, recurring categories of items actually being moved	AI-assisted variant detection identifying genuine, recurring structural variants in a collection

Quick Recap

• Polymorphic document collections hold genuinely different variants of a related concept within the same collection, each with its own appropriate structure.
• A discriminator field is the classic pattern for making this variety explicit and queryable, distinguishing genuine variation from simple missing data.
• AI-assisted variant detection can distinguish genuine polymorphic structure from accidental inconsistency, and AI-assisted schema documentation can catalog a collection’s real variants.
• AI agents need clear discriminator conventions to correctly interpret and query documents across a polymorphic collection’s different variants.

Where This Fits in the Series

Article 4 covered packing for how you’ll actually unpack. This article covered the truck’s natural tolerance for variety. Article 6 looks at two boxes with the same label but different contents — schema versioning in a schemaless world.