Wikidata:Stable Interface Policy

This page documents an operational policy of www.wikidata.org. It is a statement of intent given by the engineering team responsible for developing the Wikibase software and managing the Wikidata site.

Stable public interfaces for data access are a crucial component of any public knowledge repository. This Stable Interface Policy defines which guarantees are and are not given by the Wikidata development team regarding the stability of data formats and APIs provided by Wikibase as deployed on www.wikidata.org.

This section defines some crucial terms used in this document.

• Consumer: software that reads and interprets data received from Wikidata.
• Client: software that calls public Wikidata APIs. Clients are typically also consumers of data.
• Compliant client/consumer: A client or consumer that complies with the specification of the underlying formats and protocols it uses. For instance, a compliant consumer that reads JSON data complies with the JSON specification, and will accept any encoding allowed by the JSON specification (RFC 7159). A compliant client using a web API will comply with the HTTP spec, etc.
• Well behaved client/consumer: A (compliant) client or consumer which is implemented in a robust and forward-compatible way, specifically taking into account the guarantees and limitations stated in this document. For instance, a well-behaved client will not break when encountering a new data type.
• Breaking change: a change to an API or data format that violates guarantees given or widely assumed before. Breaking changes include removal of API functions, parameters, or data fields and changes to the interpretation or format of parameters or data fields.
• Significant change: a change to an API or data format that would be beneficial for clients or consumers to adapt to, but which will not break a well behaved client or consumer. Significant changes particularly include additions, such as the introduction of new data types or entity types, or the inclusion of additional information in the data output. See Extensibility below.
• Insignificant change: a change to an API or data format that is not expected to have any impact in a well-behaved client. Insignificant changes include changes to whitespace outside literals as well as the order of fields in a JSON object.
• Stable Interface: an API or data format for which breaking and significant changes will be announced as per the below policy. Which interfaces are considered stable is defined in the Stable Interfaces later in this document.

This section defines where and when the operators of clients and consumers will be notified of changes to a stable interface. No guarantees are made regarding unstable interfaces.

• Breaking changes to stable interfaces will be duly announced in advance on the relevant mailing lists (wikidata-tech, wikidata and pywikibot) and on the Project Chat. The announcement will generally be made four weeks before, but no less than two weeks before the change is deployed to https://www.wikidata.org/. The change will be available for testing at least two weeks before deployment on https://test.wikidata.org/. Such announcements will have the word BREAKING in the subject line.
• Significant changes to stable interfaces will be announced on the relevant mailing lists (wikidata-tech, wikidata and pywikibot) and on the Project Chat. The announcement will generally be made at least two weeks in advance, but no less than one week after the change was deployed to https://www.wikidata.org/. The change will typically be available for testing at least two weeks before deployment on https://test.wikidata.org/.
• Insignificant changes to stable interfaces will generally not be announced.
• Changes to non-stable interfaces may not be announced, even if they are breaking changes.
• Significant changes to this policy will be announced on the relevant mailing lists (wikidata-tech and wikidata) and on the Project Chat within a week of the change being made.

This section explains in which way our data model and data formats are extensible. Consumers should consider this information in order to accommodate unknown structures they may encounter in the data.

The Wikibase Data Model is designed to be extensible. In particular, it is possible to introduce new data types and new entity types. Well-behaved clients and consumers should thus be prepared to encounter unknown data types and entity types, and handle them gracefully, in a way appropriate for the use at hand. In many cases, it is appropriate to simply ignore such structures of unknown type.

Similarly, bindings such as the JSON representation of the Wikibase data model are designed to be extensible. Data structures may be added in any syntactically appropriate place as long as they do not modify the meaning of pre-existing fields or data structures, and as long as their addition does not break any guarantees regarding the containing data structures. This follows the idea of the Liskov substitution principle: what was guaranteed about a data structure before the addition should still be guaranteed after the addition.

If no explicit guarantees are given regarding the structure and contents of a data structure, the following principles should give guidance regarding whether a change should be considered a breaking change:

In structures based on lists (aka. arrays) and maps (aka. hashes or objects), like JSON is, adding a key to a map is not considered a breaking change, as long as the new field does not change the interpretation of any other fields in the structure (nor in any surrounding structure). Adding a structure to a list or set however is considered a breaking change if it would break assumptions about the type of structure to expect in the list, or under what conditions a structure would be included in the list.

By convention, lists are considered homogeneous, and should only contain one kind of element, unless otherwise specified. So adding a data structure to a list is a breaking change if that data structure is not compatible with the type of structure that the list was previously defined or implied to contain.

In a tabular data representation, such as a relational database schema, the addition of fields is not considered a breaking change. Any change to the interpretation of a field, as well as the removal of fields, are considered breaking. Changes to existing unique indexes or primary keys are breaking changes; changes to other indexes as well as the addition of new indexes are not breaking changes.

In DOM-like structures based on nested typed elements with attributes, like XML is, adding an attribute is not considered a breaking change, as long as the new attribute does not change the interpretation of any other fields in the structure (nor in any surrounding structure). Adding a new type of element to a parent element is also not considered breaking, if that parent element is heterogeneous and essentially acts like a map. However, if the parent element is defined or implied to be a homogeneous list of a specific kind of child element, adding another kind of element is considered a breaking change.

For data formats that allow namespacing, like XML does, names (attribute names, element names) that belong to a namespace not explicitly mentioned by the specification of the data format can be ignored by consumers. Addition and changes to data structures from other namespaces are not considered breaking changes.

In contrast, the following modifications are examples of breaking changes, and can thus not be used to extend a format: removal of fields, changes to the type or format of a primitive value, changes to the interpretation or role of a data field, as well as changes to the element type of a collection as described above.

This section lists the data formats we consider stable. These data formats are subject to the above notification policy.

The RDF mapping of the Wikibase Data Model, as used in RDF dumps as well as in the Linked Data Interface and the Query Service, is considered a stable data format. The Wikibase vocabulary is formally defined by http://wikiba.se/ontology. Any changes to the structure or interpretation of the mapping are subject to the above notification policy. As per the general principles of RDF, additional information introduced at any time, in any location, about any subject, is not considered a breaking change.

The JSON binding of the Wikibase Data Model as used in JSON dumps, with the web API, and with the Linked Data Interface, is considered a stable data format. Any changes to the structure or interpretation of the mapping are subject to the above notification policy. Following the flexible nature of JSON, the addition of fields to JSON objects is not considered a breaking change. Well-behaved consumers should be prepared to ignore such additional fields.

This section lists the interfaces we consider stable. These interfaces are subject to the above notification policy.

The Wikibase Web API accessible via https://www.wikidata.org/w/api.php is considered a stable interface. Changes to the parameters, operation, or returned data structure are subject to the above notification policy.

The Linked Data Interface accessible via https://www.wikidata.org/wiki/Special:EntityData and https://www.wikidata.org/entity/... is considered a stable interface. Changes to the parameters, operation, or returned data structure are subject to the above notification policy.

The Wikidata Query Service accessible via https://query.wikidata.org/ is considered a stable interface. It provides a full SPARQL endpoint. Changes to the parameters, operation, or returned data structure are subject to the above notification policy.

The Wikibase Lua library for client wikis is considered a stable interface. Changes to the available functions, parameters, or returned data structures are subject to the above notification policy.

To allow better gadget integration JavaScript hooks documented in the hooks-js.md file delivered together with Wikibase source code are considered stable.

We acknowledge that third party tools on Cloud VPS and Toolforge may rely on the Wikibase database schema. Because of this, changes to the available tables and fields are subject to the above notification policy. However, note that the database schema is not designed to be a public API, and less consideration is given to backwards compatibility.

This section lists some interfaces that we do not currently consider stable, and thus may change in incompatible ways without notice.

MediaWiki XML Dumps are not considered a stable interface. MediaWiki XML dumps contain the raw data of page revisions in their internal representation. The internal representation of Wikibase entities is not a stable interface. It has changed significantly in the past, and it may change again in the future. Several different representations of Wikibase content may be present in the same XML dump.

Raw revision content as returned by the MediaWiki core API is not considered a stable interface, as it uses the internal representation of the content, just like the XML dumps. Raw revision content is returned from API queries such as api.php?action=query&prop=revisions&titles=Q42&rvprop=timestamp|user|comment|content.

Wikibase PHP code is not considered a stable interface. Although the Wikibase project now provides official releases, wikidata.org still receives rolling deployment of Wikibase code. Therefore there is no point in time at which any given PHP class or interface can be assumed to remain stable.

Wikibase JavaScript code is not considered a stable interface. Although the Wikibase project now provides official releases, wikidata.org still receives rolling deployment of Wikibase code. Therefore there is no point in time at which JavaScript code can be assumed to remain stable. This means that Gadgets cannot rely on the JavaScript code to remain stable.

The HTML DOM structure generated by Wikibase is not considered a stable interface. This means that Gadgets cannot rely on the DOM structure to remain stable.

This section provides information about improvements that are planned or considered for the future.

The JSON binding should be versioned (using the semantic versioning convention), so consumers know what structures to expect, and how to interpret them. See phab:T92961.

Wikibase JavaScript code should indicate stable interfaces that can be confidently used by Gadgets.

Wikibase should provide some basic guarantees about the HTML DOM structure it generates, so Gadgets can confidently interact with the DOM.

For 3rd party installations, Wikibase now has regular releases linked to MediaWiki releases. However, Wikidata will continue to use rolling deployments of the latest development version.

This section lists past and scheduled breaking changes, with the newest on top. The list of past changes before the implementation of this policy may be incomplete. Each change should be listed with the date of announcement and the date of deployment, ideally accompanied with a link to the announcement and any relevant tickets.

• 2025-02-XX: [BREAKING CHANGE ANNOUNCEMENT] Wikidata Query Service graph split available in production; scholarly entity queries require migration by March 2025 announced 2024-09-03
• 2024-07-15: [Significant Change Announcement] New "mul" term language code on Wikidata. announced 2024-07-22
• 2024-07-02: [Significant Change Announcement] [DOT] Upcoming Changes to Wikibase: EntitySchema data type. announced 2024-06-19
• 2024-02-19: [Significant Change Announcement] Upcoming Changes to Wikibase API Modules: Addition of New Parameters. announced 2024-02-19
• 2024-01-24: [Breaking Change Announcement] Empty Senses / Forms Lists Presentation in Lexeme Dumps. announced 2024-01-24, deployed 2024-01-08
• 2023-05-18: [Breaking Change Announcement] Entity Labels Added to Parsed Edit Summaries in API Requests. announced 2023-05-04
• 2023-05-18: [Breaking Change Announcement] Inconsistencies in the response of `list=wbsubscribers` API Query module. Announced 2023-05-04
• 2023-05-17: [Breaking Change Announcement] Changes to the wblistentityusage API module. Announced 2023-05-03
• 2022-07-26: New search profile parameter in Wikidata’s wbsearchentities API module. Announced 2022-07-26
• 2021-09-06: Breaking change to the web API: data value normalization on saving an edit. Announced 2021-08-23
• 2021-05-27: Wikidata forms without statements use empty JSON array instead of empty JSON object. Announced 2021-05-27
• 2021-03-03: Breaking change to the web API: wbeditentity response uses standard serialization now. (Breaking only for MediaInfo entities, significant for some other entity types.) Announced 2021-02-08
• 2020-08-05: Breaking change to the web API: removing special pageterms behavior on repo wikis, use entityterms instead. Announced 2020-07-15
• 2020-04-16: Blank node deprecation in WDQS & Wikibase RDF model. Announced 2020-04-16
• 2019-05-06: Breaking change to the web API of the WikibaseQualityConstraints extension: default value of status parameter now include the new "suggestion" constraint status. Announced 2019-04-17
• 2019-04-30: Breaking change to the JSON serialization: empty containers in JSON outputs will be serialized as empty object instead of empty array. Announced 2019-04-02
• 2018-11-16: Breaking change to RDF representation: the "beta" in ontology prefix is dropped. Announced 2018-10-17
• 2018-02-26: Breaking change to the web API of the WikibaseQualityConstraints extension: default value of status parameter is changed. Announced 2018-01-29
• 2017-12-18: Breaking change to the web API of the WikibaseQualityConstraints extension: wbcheckconstraints output no longer includes detail and detailHTML of constraints. Announced 2017-11-20
• 2017-10-10: Breaking change to the web API of the WikibaseQualityConstraints extension: wbcheckconstraints returns its results in a new output format. Announced 2017-09-14
• 2016-11-25: Breaking change to the web API, JSON binding, and RDF mapping: upper- and lower bound of Quantity values are becoming optional. Announced 2016-11-04
• 2015-09-09: Breaking change to the XML representation of API output. Announced 2015-08-27
• 2015-06-15: Breaking change to the JSON serialization, replacing type:claim with type:statement. Announced 2015-06-15
• 2014-08-22: Breaking change to Special:Export to use the same JSON output as the web API. Announced 2014-08-15
• 2013-09-10: Breaking change to the web API output: Q-IDs are now upper-case. Announced 2013-09-10
• 2013-06-16: Breaking change to the web API: wbeditentity now requires that either the 'id' parameter or the 'new' parameter be set. Announced 2013-06-16.