Page MenuHomePhabricator

Document interface stability policy for Wikibase
Closed, ResolvedPublic


We should make clear to 3rd party users of our data and APIs what stability guarantees we give (and don't give).

The idea is to make explicit the implications of the robustness principle in the context of Wikibase.

In particular:

  • JSON and XML may contain additional fields, attributes, or elements in any location. Additional fields do not influence the interpretation of pre-existing fields, and can thus be safely ignored.
  • Entity types, data types, and value types may be added. Clients should handle unknown kinds of elements or values gracefully (typically be skipping them, or passing them through unchanged).

We should also make clear which interfaces are considered stable:

  • The MediaWiki web API modules are considered a stable interface. This also applies to the serialization formats supported for output.
  • "stable" currently does not mean "versioned". It currently only means that due notice will be given of breaking changes. For interface versioning, see T92961: [Story] Versioning in JSON output
  • Other stable interfaces are the output of Special:EntityData and the format used in JSON and RDF dumps.
  • The contents of MediaWiki XML dumps is not a stable interface.

Finally, we should adopt a policy for due notice of significant changes:

  • distinguish between "breaking" and "significant". Changing the way we serialize time values would be "breaking", adding a new data type would not be "breaking", but still "significant".
  • establish channels and notice periods for significant and breaking changes.

Some key parts of such a policy document are outlined in an email to wikitech-l from February 5 2016: On interface stability and forward compatibility.

The policy needs to be findable on, and should be prominently linked from Wikibase/DataModel/JSON and similar pages.

Event Timeline

A draft is now up at A request for final comments has gone out to the wikidata and wikidata-tech lists, as well as the project chat:

Putting this on "review" for the feedback period. The policy should be announced on August 22, barring substantial objections.