Future API standard evolution

Scope extensions

Proposals for scope extensions in a future version of the API standard will follow the process documented at https://github.com/data-apis/governance/blob/master/process_document.md

In summary, proposed new APIs go through several maturity stages, and will only be accepted in a future version of this API standard once they have reached the “Final” maturity stage, which means multiple array libraries have compliant implementations and real-world experience from use of those implementations is available.

Backwards compatibility

Functions, objects, keywords and specified behavior are added to this API standard only if those are already present in multiple existing array libraries, and if there is data that those APIs are used. Therefore it is highly unlikely that future versions of this standard will make backwards-incompatible changes.

The aim is for future versions to be 100% backwards compatible with older versions. Any exceptions must have strong rationales and be clearly documented in the updated API specification.

Versioning

This API standard uses the following versioning scheme:

  • The version is date-based, in the form yyyy.mm (e.g., 2020.12).

  • The version shall not include a standard way to do alpha/beta/rc or .post/.dev type versions. Rationale: that’s for Python packages, not for a standard.

  • The version must be made available at runtime via an attribute __array_api_version__ by a compliant implementation, in 'yyyy.mm' format as a string, in the namespace that implements the API standard. Rationale: dunder version strings are the standard way of doing this.

No utilities for dealing with version comparisons need to be provided; given the format simple string comparisons with Python operators (=-, <, >=, etc.) will be enough.

Note

Rationale for the yyyy.mm versioning scheme choice: the API will be provided as part of a library, which already has a versioning scheme (typically PEP 440 compliant and in the form major.minor.bugfix), and a way to access it via module.__version__. The API standard version is completely independent from the package version. Given the standardization process, it resembles a C/C++ versioning scheme (e.g. C99, C++14) more than Python package versioning.

The frequency of releasing a new version of an API standard will likely be at regular intervals and on the order of one year, however no assumption on frequency of new versions appearing must be made.