On this page

Polymorphic Variants

Published on August 8, 2026

Enrico Hochkoeppler Profile

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​

Found this helpful? Share the knowledge...

... or support this project to keep it alive!

Buy Me a Coffee

Previous

Custom Operators & Precedence Rules

Next

Tail Recursion, Accumulators & Stack Safety