- Courses
- 💻Programming Languages
- 🐫OCaml (WIP)
- Functional Design Idioms
- Polymorphic Variants
On this page
Polymorphic Variants
Published on August 8, 2026
By Enrico Hochkoeppler
Web Developer & TutoriaLibre Founder
Polymorphic variants behave like ordinary variants at the value level — a tag, optionally carrying data — but need no type declared in advance, and are typed structurally rather than by name. Two polymorphic variant values written in completely unrelated parts of a program are automatically compatible with each other as long as their tags line up, which is precisely the flexibility ordinary variants don't offer, and precisely the source of the sharper edges polymorphic variants come with.
Basic Syntax
A polymorphic variant tag is written with a leading backquote, and needs no corresponding type ... = ... declaration anywhere before it's used:
let status_message = function
| `Pending -> "waiting to ship"
| `Shipped tracking -> "shipped, tracking: " ^ tracking
| `Delivered -> "delivered"
# status_message `Pending;;
- : string = "waiting to ship"
# status_message (`Shipped "1Z999");;
- : string = "shipped, tracking: 1Z999"
Nothing here declared a type named, say, shipment_status — OCaml infers the type of status_message's argument directly from how the tags are used inside the function body, producing a type written with square brackets rather than a named type:
# status_message;;
- : [< `Delivered | `Pending | `Shipped of string ] -> string = <fun>
The square brackets don't denote a list here; they enclose the set of tags this particular type is built from.
Structural Typing: Compatibility Without a Shared Declaration
Because there's no named type acting as a single source of truth, two independently written pieces of code can produce and consume polymorphic variant values that happen to share compatible tags, with no explicit connection between them at all:
let make_pending () = `Pending
let describe = function
| `Pending -> "still waiting"
| `Delivered -> "arrived"
# describe (make_pending ());;
- : string = "still waiting"
make_pending and describe were never linked through a shared type definition — describe simply accepts any value carrying a `Pending or `Delivered tag, and make_pending's result happens to satisfy that. With ordinary variants, this kind of compatibility only happens when both pieces of code are written against the exact same named type; with polymorphic variants, it happens automatically, purely from the tags themselves lining up.
Lower Bounds and Upper Bounds
The type OCaml infers for a function using polymorphic variants depends on whether its pattern match is closed (every possible tag is spelled out) or left open with a catch-all case, and this distinction shows up directly in the inferred type as an upper or lower bound.
A fully exhaustive match, with every tag explicitly listed and no wildcard, infers an upper bound, written with <, meaning the argument may carry at most these tags:
# describe;;
- : [< `Delivered | `Pending ] -> string = <fun>
A match that includes a catch-all case instead infers a lower bound, written with >, meaning the argument must carry at least these tags, but is free to carry more besides:
let is_final = function
| `Delivered -> true
| _ -> false
# is_final;;
- : [> `Delivered ] -> bool = <fun>
is_final will happily accept a value carrying `Delivered, `Pending, `Cancelled, or any other tag at all — the wildcard case means the function doesn't actually need to know the full set of possible tags in advance, only how to handle the one it specifically cares about.
Where Polymorphic Variants Genuinely Help
The clearest use case is a small, ad hoc tag that would feel like unnecessary ceremony to formalize as its own named variant type — encoding a function's handful of specific input or output cases where declaring a dedicated type block purely for one function's use adds more overhead than value. They're also genuinely valuable in library interfaces specifically designed to stay open to extension, where a function is meant to accept tags the library's own author didn't necessarily anticipate, or where two otherwise-unrelated parts of a codebase need to interoperate around a shared shape of data without importing a single, centrally declared type between them.
Where They Genuinely Hurt
The same flexibility that makes polymorphic variants convenient also removes a safety net ordinary variants provide by default. Since there's no named type acting as ground truth, there's no fixed list of constructors for the compiler to check a pattern match against, and no single declaration to update — and have the compiler immediately flag every affected call site — when a tag's meaning changes. A typo in a tag name, such as writing `Deliverd instead of `Delivered, usually doesn't produce a clear "unknown constructor" error the way misspelling an ordinary variant constructor would; instead, it tends to surface later, as a type mismatch somewhere else entirely, once the mistyped tag's inferred type stops lining up with what the rest of the code expects.
Combining a catch-all wildcard with polymorphic variants compounds this risk. A wildcard case on an ordinary variant is already a known trap, since it silently absorbs any newly added constructor rather than forcing every relevant branch to be revisited. With polymorphic variants, that same trap is easier to fall into by accident, precisely because there's no fixed set of tags anywhere to remind a reader what the wildcard might actually be catching. Being deliberately more careful about writing exhaustive matches, and making the intended set of tags explicit through a type annotation where it matters, is the practical mitigation.
A Small Runtime Cost
Polymorphic variant tags don't get the same compact, compiler-assigned small integer representation that ordinary variant constructors do; each tag is instead hashed to an integer at runtime the first time it's used. This makes values built from polymorphic variants slightly heavier than their ordinary-variant equivalents, though the difference is generally only noticeable on very large, tag-heavy data structures rather than everyday code.
Choosing Between the Two
For everyday application code, ordinary variants remain the safer default: a named type acts as a fixed point of reference, keeps the compiler's exhaustiveness checking fully effective, and gives a clear, centrally located place for every possible case to be documented. Polymorphic variants are worth reaching for deliberately, in the specific situations where their structural flexibility is actually the point — a small, one-off tag that doesn't warrant its own type declaration, or a library interface intentionally designed to stay open to tags its author didn't originally anticipate — rather than as a general substitute for ordinary variants throughout a codebase.
Key Takeaways
- Polymorphic variant tags start with a backquote and need no type declared in advance; OCaml infers their type structurally, from how the tags are actually used.
- Two independently written pieces of code can interoperate around polymorphic variant values automatically, as long as their tags are compatible, with no shared named type required.
- A closed, fully exhaustive match infers an upper bound (
[< ... ], at most these tags); a match with a catch-all case infers a lower bound ([> ... ], at least these tags). - The clearest genuine use cases are small, ad hoc tags not worth formalizing as their own type, and library interfaces deliberately designed to accept tags beyond what the author explicitly anticipated.
- Without a fixed named type to check against, typos in tag names tend to surface as confusing type mismatches elsewhere rather than clear errors, and catch-all wildcards are an even easier trap to fall into than with ordinary variants.
- Ordinary variants remain the more maintainable default for everyday code; polymorphic variants are a deliberate choice for the specific situations where structural flexibility is genuinely needed.
Found this helpful? Share the knowledge...
... or support this project to keep it alive!
Previous
Custom Operators & Precedence Rules
Next
Tail Recursion, Accumulators & Stack Safety
- Basic Syntax
- Structural Typing: Compatibility Without a Shared Declaration
- Lower Bounds and Upper Bounds
- Where Polymorphic Variants Genuinely Help
- Where They Genuinely Hurt
- A Small Runtime Cost
- Choosing Between the Two
- Key Takeaways
