Hyrum's Law
Also known as: Law of Implicit Interfaces
With enough users, every observable behavior of an interface becomes someone's dependency.
Hyrum's Law was articulated by Hyrum Wright at Google around 2017 (popularized through hyrumslaw.com and through Software Engineering at Google, 2020) and states: 'With a sufficient number of users of an API, it does not matter what you promise in the contract: all observable behaviors of your system will be depended on by somebody.' The law captures the empirical reality that as APIs gain users, the gap between the documented contract and the actual behavior of the implementation becomes a dependency surface — users discover incidental behaviors (timing, error message strings, ordering of unspecified outputs, performance characteristics) and write code that depends on those behaviors, often unknowingly. Changing the implementation in ways that preserve the documented contract but alter incidental behavior breaks those users. The law is empirically grounded in Google's experience maintaining widely-used APIs and is sharply visible in standards-body work: HTML and JavaScript implementations have been forced to preserve historical bugs because real-world content depends on the bug behavior. Hyrum's Law reframes API maintenance from contract-stability to behavior-stability, with substantial implications for backward-compatibility strategy, deprecation, and the value of strict-by-default protocol design (the modern critique of Postel's Law).
Core components
- All observable behaviors become dependencies at sufficient scale
- Distinction between contract (documented) and observable behavior (actual)
- Implications for backward compatibility
- Connection to Postel's Law (liberal acceptance creates more observable behaviors to depend on)
- Strategies: hashing internal data structures, randomizing iteration orders, fault injection to break dependence on hidden invariants
- Examples from web standards (HTML, JavaScript) preserving historical bugs
- Foundation for modern thinking on protocol and API evolution
Primary use case
API and protocol design at scale; foundation for backward-compatibility strategy; basis for techniques like deliberate randomization (iteration order, ID generation) that prevent hidden dependencies; teaching framework for software engineering at scale; reference in standards-body work on protocol evolution; complement to Postel's Law in modern API thinking.
Common criticisms
- Empirical observation rather than mechanism — doesn't predict which behaviors will become dependencies
- can be invoked to rationalize over-conservative API evolution that prevents necessary improvements
- doesn't address how to balance backward compatibility against legitimate evolution needs
- works best for very widely-used APIs (Linux kernel ABI, JavaScript engines, Windows API) and has less practical force for modest-scale APIs
- some teams use Hyrum's Law as excuse to never change anything, missing that the law also implies you should be deliberate about which behaviors become observable in the first place
- the law is a constraint on evolution rather than a positive design principle.
Lineage
- Siblings
- Postel's Law