On this page

OCaml Phantom Types — Encoding Invariants the Compiler Checks for You

Published on August 20, 2026

Enrico Hochkoeppler Profile

By Enrico Hochkoeppler

Web Developer & TutoriaLibre Founder

A phantom type parameter is a type variable that appears in a type's declaration but never actually shows up in the data that type represents. It exists purely for the type checker's benefit — carrying information the compiler can track and enforce, with absolutely no trace of it left in the compiled program's runtime representation. Used correctly, this makes it possible to rule out entire categories of mistakes — mixing up units, using a resource in the wrong mode, combining values that were never supposed to be combined — entirely at compile time, for free.

What Makes a Type Parameter "Phantom"​

Consider a type parameterized over 'a, where 'a never actually appears anywhere in the definition's right-hand side:


type 'a amount = float

'a is free to be absolutely anything here, since nothing in the definition constrains it or uses it. This is already visible in the toplevel:


# (3.0 : unit amount);;

- : unit amount = 3.

# (10.0 : string amount);;

- : string amount = 10.

Both of these compile without complaint, because a bare float genuinely doesn't care what 'a happens to be — the phantom parameter is just riding along, unconnected to anything.

The Trap: A Bare Phantom Type Enforces Nothing on Its Own​

This is the point where it's tempting to assume the job is already done — write a function restricted to, say, usd amount -> usd amount -> usd amount, and expect the compiler to reject calls that mix in some other tag. It doesn't, not yet:


let add (a : 'c amount) (b : 'c amount) : 'c amount = a +. b

# add (3.0 : unit amount) (5.0 : string amount);;

Because unit amount and string amount are both, underneath, simply float, and nothing has told the compiler these two tags are supposed to be incompatible, it happily unifies 'c across the call and lets it through — the phantom parameter alone carries no restriction, since it was never actually anchored to anything at every point that matters. A phantom type parameter only becomes a genuine safety mechanism once it's paired with encapsulation that controls exactly how values of the type are produced in the first place.

The Working Pattern: Phantom Type Plus Restricted Constructors​

Wrapping the phantom type in a module, keeping its representation abstract, and exposing only tag-specific constructor functions is what actually makes the invariant hold:


module Amount : sig

  type usd

  type eur



  type 'currency t



  val usd : float -> usd t

  val eur : float -> eur t

  val add : 'c t -> 'c t -> 'c t

  val to_float : 'c t -> float

end = struct

  type usd

  type eur



  type 'currency t = float



  let usd x = x

  let eur x = x

  let add a b = a +. b

  let to_float t = t

end

usd and eur are themselves empty, abstract types — never intended to hold any actual values, existing purely to serve as distinct tags. Because Amount.usd : float -> usd Amount.t is the only way to produce a usd Amount.t, and Amount.eur is the only way to produce a eur Amount.t, Amount.add genuinely can no longer be called with one of each:


# Amount.add (Amount.usd 10.0) (Amount.eur 5.0);;

Error: This expression has type Amount.eur Amount.t

       but an expression was expected of type Amount.usd Amount.t

The difference from the earlier, unrestricted version is entirely in what's hidden: outside the Amount module, there is no way to construct a usd t except by calling Amount.usd, and no way to treat a eur t as a usd t, since the module never exposes anything that would let one be coerced into the other. This is the essential recipe — the phantom parameter provides the vocabulary for the distinction, and module encapsulation is what actually enforces it.

A Second Pattern: Capability Tags​

Phantom types are equally well suited to tracking what's allowed to be done with a value, rather than what kind of value it is. A handle that can be widened from read-write to read-only, but never the other way, is a natural fit:


module Handle : sig

  type read_only

  type read_write



  type 'perm t



  val create : int -> read_write t

  val get : 'perm t -> int

  val set : read_write t -> int -> unit

  val read_only : 'perm t -> read_only t

end = struct

  type read_only

  type read_write



  type 'perm t = int ref



  let create x = ref x

  let get t = !t

  let set t x = t := x

  let read_only t = t

end

Handle.set only accepts a read_write Handle.t, so a handle that's been narrowed with Handle.read_only can no longer be mutated — the compiler rejects any attempt directly, without a single runtime check anywhere in the implementation. Handle.get accepts either tag, since reading is always safe regardless of which capability a handle currently carries. The phantom parameter here isn't describing what kind of data the handle holds — the underlying int ref never changes — it's describing what operations are currently permitted on it, entirely at the type level.

Why This Costs Nothing at Runtime​

Because a phantom parameter never appears on the right-hand side of its type's definition, it leaves no trace in a compiled value's actual memory representation — a usd Amount.t and a eur Amount.t are both, at runtime, indistinguishable from a plain float. Every bit of protection phantom types provide is enforced once, during type checking, and then disappears completely from the compiled program. This is what makes them a genuinely free abstraction: the safety exists entirely on paper, checked once by the compiler, with none of the boxing, tagging, or runtime dispatch that a dynamically-checked equivalent would need.

Where Phantom Types Reach Their Limit​

Phantom types work well for tracking a single tag threaded consistently through a chain of operations that all share the same underlying representation — a currency, a permission level, a unit of measurement. They're less suited to situations where different tags are supposed to correspond to genuinely different shapes of data, rather than just a marker riding alongside an otherwise-identical representation. A phantom parameter can prevent two differently tagged values of the same underlying type from being mixed up, but it can't, by itself, force a particular constructor to only be usable when its result is tagged a specific way while another constructor of the same broader type is tagged differently — every constructor of a phantom-tagged type still shares one fixed, uniform representation, tag or no tag. Reaching for a more precise per-constructor relationship between a value's shape and its type is possible in OCaml, but requires a different, more powerful mechanism than a plain phantom parameter alone provides.

Key Takeaways​

Found this helpful? Share the knowledge...

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

Buy Me a Coffee

Previous

Abstract Types & Encapsulation

Next

GADTs