On Versioning Specifications

With a growing number of new specifications being published by first-time authors, I think it is important to pay attention to when should a specification carry a version number. For most people, giving a specification a version is a sign of forward thinking and planning for future revisions. But not every specification should have a version number.

There are no hard rules for giving technical specifications a version number. Note that I am focusing exclusively on technical specification, those with the clear objective of enabling interoperability. But there are some basic guidelines:

  1. The specification itself must have a mechanism to indicate which version is being used. If the specification includes a protocol, there should be a parameter with the version number, or at least a default version in lack of such indication. If the specification includes a schema, that schema should have a clear namespace or version.
  2. Seperate the document name from the protocol version. The specification name should not always carry a version, even when its protocol or schema have a version. A specification that does not modify the way a schema is interpreted or a protocol interoperates, does not need a version number. For example, there are multiple RFCs describing HTTP 1.1. While they differ in their language, they do not each carry a version number. Instead, they have unique names which are only used for referencing the documents, not the protocol.
  3. Specifications that extend an existing versioned specification should bind themselves to that version  and not come up with their own. For example, if you are writing an OAuth extension that is written against OAuth Core 1.0, don't version your specification seperately (unless it has its own seperate version parameter per guideline #1). Simply indicate that this extension is limited to specific versions of the core protocol.