On this page

Module Signatures (.mli Files) — Abstraction and Hiding Implementation

Published on August 3, 2026

Enrico Hochkoeppler Profile

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:

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​

Found this helpful? Share the knowledge...

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

Buy Me a Coffee

Previous

Files as Modules

Next

Nested Modules