Living Spec

When several companies are supposed to build the same product, they need a shared description of it. Such a document defines precisely what a program must be able to do and how it should behave. In the past, such descriptions were published like textbooks: Version 1, Version 2, Version 3. A living spec does this differently. It is continuously revised, and there is always only one valid version, namely today’s. Anyone who wants to know what applies looks at the current page, not at a version number.

Why fixed version numbers no longer fit

The classic model comes from a time when software was delivered on CDs. People would agree on a text for years, formally adopt it, and only then start working on the next one. The problem: often five or ten years lay between two versions. During that time, manufacturers still built in new features that didn’t appear in the official text at all.

This created a gap between paper and reality. The document described a state that had long since ceased to exist. Developers oriented themselves toward the actual behavior of the programs rather than toward the specification. It is exactly this gap that a living spec is meant to close by moving along with reality.

The best-known example is HTML, the language in which web pages are built. Since 2011 it has been maintained as a Living Standard. There is officially no longer a number attached to the name. Many projects in the field of artificial intelligence work similarly today, for instance with interfaces through which programs talk to language models.

How a living spec is maintained

The text is usually kept publicly in a version control system. That is a program that records every single change with date, author, and justification. Anyone who wants to change something proposes the change. A group of maintainers reviews the proposal, discusses it publicly, and either adopts it or rejects it.

Because there are no version numbers, a different way is needed to refer to a particular state. For this, one uses the timestamp or the unique identifier of a change. This way, a company can document: our product complies with the state as of March 3rd.

An important rule is that existing features must not simply break. New things are added, outdated ones are first marked as deprecated and only removed much later. Without this consideration, every change would cripple millions of existing web pages or programs. A living spec is therefore not a free pass for arbitrary overhauls, but a very disciplined process.

The term in product announcements and contracts

You most often encounter this principle on the web. Every browser on your phone implements a living spec. The rules for video formats or for payment processes in the browser are also maintained this way. Normally you don’t notice it at all, except that new features simply become available at some point.

In the AI industry, the term currently comes up often when companies publish open interfaces. Such descriptions sometimes change on a monthly basis, because the technology moves so fast. Announcements like “the specification has been extended” then don’t refer to a new edition, but to a new state of the same document.

For companies, this has a very concrete side. Contracts and certification seals like to refer to a fixed text that does not change. With a living spec, one must therefore precisely record which state is meant. Another common misconception is that “living” means “unfinished.” The opposite is true: the text is complete at all times, it just never stops improving.