Hyrum's Law
With enough users, every observable behaviour of a system will be depended on by somebody, regardless of what the contract promises.
Also known as: Law of Implicit Interfaces, Hyrum's law of implicit dependencies
Category: Software Development
Tags: software-development, api-design, laws, compatibility, architecture
Explanation
Hyrum's Law, formulated by Google engineer Hyrum Wright, states that with a sufficient number of users of an API, it does not matter what you promise in the contract: all observable behaviours of your system will be depended on by somebody. Users build against what the system actually does, not what its documentation says it guarantees. Documented interfaces and undocumented accidents are indistinguishable from the outside, so timing characteristics, error message text, the iteration order of an unordered collection, memory layout, and even the presence of a bug all become part of the effective interface. The practical consequence is that any change, including a bug fix or a performance improvement, can break a downstream consumer. Large platforms accumulate compatibility shims specifically to preserve behaviour they never intended to promise. The defences are preventive: hide implementation details behind narrow interfaces, deliberately randomise behaviour that is not guaranteed so nobody can depend on it, test against real consumer usage rather than only against the specification, and version and deprecate explicitly. The law also explains why mature systems calcify, since with enough users every detail becomes load-bearing.
Related Concepts
← Back to all concepts