- Courses
- 💻Programming Languages
- 🐫OCaml (WIP)
- Modules, Structure & Tooling
- Module Signatures
On this page
Module Signatures (.mli Files) — Abstraction and Hiding Implementation
Published on August 3, 2026
By Enrico Hochkoeppler
Web Developer & TutoriaLibre Founder
A .ml file defines what a module actually does; a .mli file defines what that module is allowed to show the rest of a program. Without one, every single definition in a module is automatically public — every function, every type, every helper, all visible and usable from anywhere else in the project. A .mli file changes that default, acting as a mask placed over the implementation, exposing only a deliberately chosen subset of it.
The Default: Everything Is Public
A module built from a file with no matching .mli exposes its entire contents. Consider a small module for tracking a running total:
(* total.ml *)
let clamp x = if x < 0 then 0 else x
let add total x = clamp (total + x)
With no total.mli present, both clamp and add are fully visible and callable as Total.clamp and Total.add from anywhere else in the project — including clamp, which was really only meant as an internal helper for add.
Restricting What's Visible
Adding a .mli file with the same base name changes this. A signature lists exactly which values (and types) are exposed, using val declarations:
(* total.mli *)
val add : int -> int -> int
With this file in place, Total.add still works exactly as before, but Total.clamp is no longer accessible from outside total.ml at all — it still exists and still runs internally, but it's now a genuinely private implementation detail, invisible to every other module in the project. Nothing about total.ml itself needs to change to achieve this; the .mli file alone is what draws the line between public and private.
Enforcing Invariants Through Abstract Types
Hiding a helper function is useful, but the more powerful use of a .mli file is hiding a type's representation, which makes it possible to guarantee properties about a type that couldn't be guaranteed if its internal structure were visible to every caller. Consider a stack with a fixed maximum capacity:
(* bounded_stack.ml *)
type 'a t = { items : 'a list; capacity : int }
let create capacity = { items = []; capacity }
let push x s =
if List.length s.items >= s.capacity then failwith "stack is full"
else { s with items = x :: s.items }
let pop s =
match s.items with
| [] -> None
| h :: t -> Some (h, { s with items = t })
Without a .mli file, nothing stops another part of the program from building a Bounded_stack.t value directly, bypassing push entirely and violating the capacity limit the type is supposed to guarantee:
let broken = { Bounded_stack.items = [1; 2; 3; 4; 5]; capacity = 2 }
Writing a .mli file that exposes the type abstractly — giving only its name, not its internal structure — closes this loophole entirely:
(* bounded_stack.mli *)
type 'a t
val create : int -> 'a t
val push : 'a -> 'a t -> 'a t
val pop : 'a t -> ('a * 'a t) option
With type 'a t given no definition in the signature, callers outside bounded_stack.ml know that a 'a t exists and can be passed around, but have no way to construct or take one apart except through create, push, and pop — the only three functions the module chose to expose. Since every one of those functions already respects the capacity invariant, and there's no other way to produce a value of type 'a t at all, the invariant is now guaranteed for every Bounded_stack.t that could ever exist anywhere in the program.
Four Ways to Handle a Type in a Signature
A type appearing in a module's implementation can be handled in a .mli file in one of four distinct ways, each with a different trade-off between flexibility and transparency:
- Omitted entirely — the type doesn't appear in the signature at all, meaning it's completely private and can't even be named from outside the module.
- Copied concretely — the full type definition is repeated in the signature exactly as written in the implementation, meaning callers can pattern-match on it and construct it directly, with no restriction at all.
- Made abstract — only the type's name appears, as with
'a tabove, hiding its representation entirely and forcing every interaction to go through the module's exposed functions. - Made private — for a record or variant type specifically, writing
type t = private { field : int }allows callers to read fields or pattern-match on the type, but not to construct new values of it directly; only the module's own functions can build one.
The private option is a useful middle ground worth knowing about: it keeps the convenience of exposing a concrete shape for reading and pattern matching — genuinely useful in code that consumes the type — while still funneling every act of construction through functions that can validate or normalize the data first, exactly the same protection the fully abstract version offers, just without hiding the shape from readers entirely.
Why Abstraction Makes Implementations Safe to Change
Because outside code can only reach a module's contents through whatever the .mli file exposes, the implementation behind that signature is free to change completely, as long as the signature itself — and the behavior it promises — stays the same. Bounded_stack could be rewritten to use an array instead of a list internally, entirely for performance reasons, and every single caller of create, push, and pop would continue working without a single change, since none of them were ever able to depend on the list representation in the first place. This is the practical payoff of hiding implementation behind a signature: a module's internals become genuinely free to evolve, precisely because nothing outside the module was ever allowed to depend on them.
Mismatches Between .ml and .mli Are Compile-Time Errors
OCaml checks a module's implementation against its signature at compile time, and several common mistakes are caught immediately as a result. A function whose actual type doesn't match its declared signature fails to compile, as does a signature that declares a value the implementation never actually provides. Even the order of a variant type's constructors or a record's fields matters: if a type is exposed concretely in a signature, its declared order has to match the implementation's order exactly, or the build fails with an explicit mismatch error identifying exactly which declaration doesn't line up. This tight checking is part of what makes the .mli file a genuine contract rather than just documentation — breaking it is caught immediately, rather than surfacing later as a subtle runtime bug.
Documentation Belongs in the .mli File
Since a .mli file is what every external caller of a module actually reads, it's the natural place to document a module's public behavior. Comments beginning with a double asterisk are recognized by OCaml's documentation tooling and rendered directly into generated documentation:
(** Bounded, fixed-capacity stack. *)
type 'a t
(** [create capacity] returns an empty stack that can hold at most
[capacity] elements. *)
val create : int -> 'a t
Writing this documentation directly alongside each val declaration keeps a module's public contract and its explanation of that contract in exactly the same place, rather than scattered separately from the interface it describes.
Key Takeaways
- A module with no
.mlifile exposes everything it defines; adding one restricts visibility to exactly what the signature lists. - Making a type abstract in a
.mlifile — giving only its name — is what allows a module to guarantee invariants about that type, since callers can no longer construct or inspect it except through the functions the module chose to expose. - A type in a signature can be omitted, copied concretely, made fully abstract, or made private (readable and matchable, but not directly constructible) — each offering a different balance between flexibility for callers and control for the module.
- Because outside code can only depend on what a signature exposes, a module's internal implementation can be rewritten freely as long as its signature and behavior stay the same.
- OCaml checks a module's implementation against its signature at compile time, catching type mismatches, missing definitions, and even reordered variant constructors or record fields as build errors.
- Doc comments (
(** ... *)) belong in the.mlifile, since that's what documentation tooling reads and what external callers actually consult.
Found this helpful? Share the knowledge...
... or support this project to keep it alive!
Previous
Files as Modules
Next
Nested Modules
- The Default: Everything Is Public
- Restricting What's Visible
- Enforcing Invariants Through Abstract Types
- Four Ways to Handle a Type in a Signature
- Why Abstraction Makes Implementations Safe to Change
- Mismatches Between .ml and .mli Are Compile-Time Errors
- Documentation Belongs in the .mli File
- Key Takeaways
