Wikidata:Stable Interface Policy

Stable public interfaces for data access are a crucial component of any public knowledge repository. ThisStable Interface Policydefines which guarantees are and are not given by theWikidata development teamregarding the stability of data formats and APIs provided byWikibaseas deployed on wikidata.org.

Definitions

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 alsoconsumersof data.
• Compliantclient/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 behavedclient/consumer: A (compliant) client or consumer which is implemented in arobustandforward-compatibleway, 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. SeeExtensibilitybelow.
• 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 theStable Interfaceslater in this document.

Notification Policy

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

• Breaking changesto stable interfaces will be duly announced in advance on the relevant mailing lists (wikidata-tech,wikidataandpywikibot) and on theProject Chat.The announcement will generally be made four weeks before, but no less than two weeks before the change is deployed tohttps:// wikidata.org/.The change will be available for testing at least two weeks before deployment onhttps://test.wikidata.org/.Such announcements will have the word BREAKING in the subject line.
• Significant changesto stable interfaces will be announced on the relevant mailing lists (wikidata-tech,wikidataandpywikibot) and on theProject Chat.The announcement will generally be made at least two weeks in advance, but no less than one week after the change was deployed tohttps:// wikidata.org/.The change will typically be available for testing at least two weeks before deployment onhttps://test.wikidata.org/.
• Insignificant changesto stable interfaces will generally not be announced.
• Changes tonon-stable interfacesmay not be announced, even if they are breaking changes.
• Significant changes tothis policywill be announced on the relevant mailing lists (wikidata-techandwikidata) and on theProject Chatwithin a week of the change being made.

Extensibility

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.

TheWikibase Data Modelis 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,bindingssuch as theJSON representationof 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 theLiskov 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 typedelementswith 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 elementisconsidered 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 ofbreaking 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.

Stable Data Formats

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

TheRDF mappingof theWikibase 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 byhttp://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.

TheJSON bindingof theWikibase Data Modelas 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 isnotconsidered a breaking change. Well-behaved consumers should be prepared to ignore such additional fields.

Stable Public APIs

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

TheWikibase Web APIaccessible viahttps:// wikidata.org/w/api.phpis considered a stable interface. Changes to the parameters, operation, or returned data structure are subject to the above notification policy.

TheLinked Data Interfaceaccessible viahttps:// wikidata.org/wiki/Special:EntityDataandhttps:// wikidata.org/entity/...is considered a stable interface. Changes to the parameters, operation, or returned data structure are subject to the above notification policy.

TheWikidata Query Serviceaccessible viahttps://query.wikidata.org/is considered a stable interface. It provides a fullSPARQL endpoint.Changes to the parameters, operation, or returned data structure are subject to the above notification policy.

TheWikibase Lua libraryfor 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 integrationJavaScript hooksdocumented in thehooks-js.mdfile delivered together with Wikibase source code are considered stable.

We acknowledge that third party tools onCloud VPSandToolforgemay rely on theWikibase 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.

Unstable Interfaces

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

MediaWiki XML Dumpsarenotconsidered a stable interface. MediaWiki XML dumps contain the raw data of page revisions in their internal representation. The internal representation of Wikibase entities isnota 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 theMediaWiki core APIisnotconsidered 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 asapi.php?action=query&prop=revisions&titles=Q42&rvprop=timestamp|user|comment|content.

Wikibase PHP codeisnotconsidered a stable interface. Although the Wikibase project now providesofficial 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 codeisnotconsidered a stable interface. Although the Wikibase project now providesofficial 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 thatGadgetscannot rely on the JavaScript code to remain stable.

TheHTML DOMstructuregenerated by Wikibase isnotconsidered a stable interface. This means thatGadgetscannot rely on the DOM structure to remain stable.

Outlook

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

TheJSON bindingshould be versioned (using thesemantic versioningconvention), so consumers know what structures to expect, and how to interpret them. Seephab:T92961.

WikibaseJavaScriptcode should indicate stable interfaces that can be confidently used by Gadgets.

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

For3rd party installations,Wikibase now hasregular releaseslinked to MediaWiki releases. However, Wikidata will continue to use rolling deployments of the latest development version.

History

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 2025announced 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 ofstatusparameter 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 ofstatusparameter is changed.Announced 2018-01-29
• 2017-12-18: Breaking change to the web API of the WikibaseQualityConstraints extension: wbcheckconstraints output no longer includesdetailanddetailHTMLof 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 theXML 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.