diff --git a/optimade.rst b/optimade.rst index 8336bf9a9..4f5798cb7 100644 --- a/optimade.rst +++ b/optimade.rst @@ -226,6 +226,28 @@ The definition of a property of an entry type specifies a type. The value of tha General API Requirements and Conventions ======================================== +Versioning of this standard +--------------------------- +This standard describes a communication protocol that, when implemented by a server, provides clients with an API for data access. + +Released versions of the standard are versioned using `semantic versioning v2 `__ in reference to changes in *that API* (i.e., not in the server-side implementation of the protocol). + +To clarify: semantic versioning mandates version numbers of the form MAJOR.MINOR.PATCH, where a "backwards incompatible API change" requires incrementing the MAJOR version number. +A future version of the OPTIMADE standard can mandate servers to change their behavior to be compliant with the newer version. +However, such changes are only considered "backwards incompatible API changes" if they have the potential to break clients that correctly use the API according to the earlier version. + +Furthermore, the addition of new keys in key-value-formatted responses of the OPTIMADE API are not regarded as "backwards incompatible API changes." +Hence, a client MUST disregard unrecognized keys when interpreting responses (but MAY issue warnings about them). +On the other hand, a change of the OPTIMADE standard that fundamentally alters the interpretation of a response due to the presence of a new key will be regarded as a "backwards incompatible API change" since a client interpreting the response according to a prior version of the standard would misinterpret that response. + +Working copies distributed as part of the development of the standard are marked with the version number for the release they are based on with an additional "~develop" suffix. +These "versions" do not refer to a single specific instance of the text (i.e., the same "~develop" version string is retained until a release), nor is it clear to what degree they contain backwards incompatible API changes. +Hence, the suffix is intentionally designed to make these version strings not to conform with semantic versioning to prevent incorrect comparisons to released versions using the scheme prescribed by semantic versioning. +Version strings with a "~develop" suffix MAY be used by implementations during testing. +However, a client that encounters them unexpectedly SHOULD NOT make any assumptions about the level of API compatibility. + +In conclusion, the versioning policy of this standard is designed to allow clients using the OPTIMADE API according to a specific version of the standard to assume compatibility with servers implementing any future (non-development) version of the standard sharing the same MAJOR version number. + Base URL --------