Wikidata:Policy för Stabila gränssnitt

Stabila offentliga gränssnitt för datatillgänglighet är en viktig del i ett offentligt kunskapslager. Denna policy för Stabila gränssnitt definierar vilka garantier som ges och inte ges av Wikidata-utvecklingsteamet angående stabiliteten i de dataformat och API-er som tillhandahålls av Wikibase på www.wikidata.org.

Definitioner

Det här avsnittet definierar några viktiga villkor för detta dokument.

• Konsument: Programvara som läser och tolkar data som tagits emot från Wikidata.
• Klient: Programvara som anropar offentliga Wikidata API:er. Klienter är vanligtvis också "konsumenter" av data.
• Kompatibel klient/konsument: En klient eller konsument som uppfyller specifikationen för de underliggande format och protokoll som används. En kompatibel konsument som läser JSON-data uppfyller till exempel JSON-specifikationen och accepterar eventuell kodning som tillåts av JSON-specifikationen (RFC 7159). En kompatibel klient som använder ett web API kommer att följa HTTP-specifikationen etc.
• Välartad klient/konsument: En (kompatibel) klient eller konsument som implementeras på ett robust och framtidskompatibelt sätt, särskilt med hänsyn till de garantier och begränsningar som anges i detta dokument. En välartad klient kommer till exempel gå sönder när den möter en ny datatyp.
• Breaking change: En ändring till ett API eller dataformat som bryter mot garantier som ges eller antagits i stor utsträckning tidigare. Detta inkluderar borttagning av API-funktioner, parametrar eller datafält och ändringar i tolkningen eller formatet av parametrar eller datafält.
• Betydande förändring: En ändring till ett API eller ett dataformat som skulle vara till nytta för kunder eller konsumenter att anpassa sig till, men som inte kommer att bryta en välskött kund eller konsument. Betydande förändringar inkluderar i synnerhet tillägg, till exempel införandet av nya datatyper eller typer av enheter, eller införandet av ytterligare information i datautmatningen. Se ''Extensibility nedan.
• 'Obetydlig förändring' : En ändring till ett API eller dataformat som inte förväntas ha någon inverkan på en välartad klient. Obetydliga förändringar inkluderar förändringar i blankutrymme utanför bokstäver samt ordning av fält i ett JSON-objekt.
• 'Stabilt gränssnitt' : ett API eller ett dataformat för vilket brytande och signifikanta ändringar kommer att meddelas enligt följande policy. Vilka gränssnitt anses stabila definieras i Stabila gränssnitt senare i det här dokumentet.

Notifikationspolicy

I det här avsnittet definieras var och när operatörer av klienter och konsumenter blir underrättade om ändringar till ett stabilt gränssnitt. Inga garantier görs för ostabila gränssnitt.

• Breaking changes till stabila gränssnitt kommer att meddelas i förväg på de relevanta postlistorna (wikidata-tech, wikidata och pywikibot) och på Bybrunnen. Meddelandet kommer i allmänhet att göras fyra veckor innan, men inte mindre än två veckor innan förändringen sätts in på https://www.wikidata.org/. Ändringen kommer att finnas tillgänglig för testning minst två veckor före utplacering på $test-webbplats. Sådana meddelanden kommer att ha ordet BREAKING i ämnesraden.
• Väsentliga ändringar till stabila gränssnitt kommer att tillkännages på relevanta adresslistor (wikidata-tech, wikidata och pywikibot) och på Bybrunnen. Meddelandet kommer i allmänhet att göras minst två veckor i förväg, men inte mindre än en vecka efter det att förändringen gjordes till https://www.wikidata.org/. Ändringen kommer vanligen att finnas tillgänglig för testning minst två veckor före distribuering på $test-webbplats.
• Obetydliga ändringar till stabila gränssnitt kommer i allmänhet inte att meddelas.
• Ändringar i icke-stabila gränssnitt meddelas inte, även om de bryter mot förändringar.
• Betydande ändringar till denna policy kommer att meddelas på de relevanta postlistorna (wikidata-tech och wikidata) och på Bybrunnen inom en vecka efter ändringen.

Utökbarhet

I det här avsnittet förklaras hur vår datamodell och dataformat är kan utökas. Konsumenterna bör överväga denna information för att ackommodera okända strukturer som de kan stöta på i data.

Wikibase datamodell är avsedd att vara utökbar. I synnerhet är det möjligt att införa nya datatyper och nya typer av entiteter. Välskötta klienter och konsumenter bör således vara beredda att möta okända datatyper och typer av enheter och hantera dem graciöst på ett sätt som är lämpligt för användningen. I många fall är det lämpligt att helt enkelt ignorera sådana strukturer av okänd typ.

På liknande sätt är bindningar som JSON-representationen av Wikibase datamodell designad för att kunna utökas. Datastrukturer kan läggas till på alla syntaktiska lämpliga platser så länge de inte ändrar betydelsen av befintliga fält eller datastrukturer och så länge som deras tillägg inte bryter mot några garantier avseende de innehållande datastrukturerna. Detta följer tanken på Liskov-substitutionsprincipen: vad garanterades om en datastruktur innan tillägget garanteras fortfarande efter tillägget.

Om inga uttryckliga garantier ges om strukturen eller innehållet i en datastruktur, bör följande principer ge vägledning om huruvida en ändring ska betraktas som en brottförändring:

I strukturer baserade på listor (aka. Arrays) och kartor (aka. Hashes eller objects), som JSON, är inte en nyckel till en karta att betrakta som en brytningsändring, så länge som det nya fältet inte ändrar tolkningen av andra fält i strukturen (ej heller i någon omgivande struktur). Att lägga till en struktur i en lista eller uppsättning anses emellertid som en brytningsändring om det skulle bryta antaganden om vilken typ av struktur som förväntas i listan eller under vilka förutsättningar en struktur skulle inkluderas i listan.

Enligt konventionen anses listor vara homogena och bör endast innehålla en typ av element, om inget annat anges. Så att lägga till en datastruktur i en lista är en brytningsändring om den datastrukturen inte är kompatibel med den typ av struktur som listan tidigare definierades eller antyddes innehålla.

I en tabellformatrepresentation, såsom ett relationsdatabasschema, anses inte addering av fält som en brytningsändring. Eventuell förändring av tolkningen av ett fält, liksom avlägsnande av fält, anses vara brytningsförändringar. Ändringar av existerande unika index eller primära nycklar är brytningsförändringar; ändringar till andra index samt tillägg av nya index är det inte.

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.

Stable Data Formats

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.

Stable Public APIs

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.

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 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.

Outlook

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.

Historia

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.

• 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.