Wikidata:Stable Interface Policy/nl

Stabiele openbare interfaces voor gegevenstoegang zijn een cruciaal onderdeel van elke openbare kennisopslagplaats. Dit Stable Interface Policy definieert welke garanties wel en niet worden gegeven door het Wikidata development team met betrekking tot de stabiliteit van gegevensformaten en API's geleverd door Wikibase zoals geïmplementeerd op www.wikidata.org.

Definities

In deze sectie worden enkele cruciale termen gedefinieerd die in dit document worden gebruikt.

• Consument: software die gegevens van Wikidata leest en interpreteert.
• Klanten: software die publieke Wikidata API's aanroept. Klanten zijn doorgaans ook consumenten van data.
• Compliant klant/consument: Een klant of consument die voldoet aan de specificatie van de onderliggende formaten en protocollen die het gebruikt. Een compatibele consument die JSON-gegevens leest, voldoet bijvoorbeeld aan de JSON-specificatie en accepteert elke codering die is toegestaan door de JSON-specificatie (RFC 7159). Een compatibele klant die een web-API gebruikt, voldoet aan de HTTP-specificatie, enzovoort.
• Goed gedrag klant/consument: Een (conforme) klant of consument die op een robuuste en voorwaarts compatibele manier wordt geïmplementeerd, specifiek rekening houdend met de garanties en beperkingen die in dit document worden vermeld. Een goede klant bijvoorbeeld niet breken wanneer het een nieuw gegevenstype tegenkomt.
• Verstorende wijziging: een wijziging in een API of dataformaat die in strijd is met eerder gegeven of algemeen aangenomen garanties. Wijzigingen worden verbroken door het verwijderen van API-functies, parameters of gegevensvelden en wijzigingen in de interpretatie of indeling van parameters of gegevensvelden.
• Significante verandering: een wijziging in een API of dataformaat die gunstig zou zijn voor klanten of consumenten om zich aan aan te passen, maar die een goede klant of consument niet zal verstoren. Belangrijke wijzigingen omvatten met name toevoegingen, zoals de introductie van nieuwe gegevenstypen of entiteitstypen, of de opname van aanvullende informatie in de gegevensuitvoer. Zie Uitbreidbaarheid hieronder.
• Onbeduidende wijziging: een wijziging in een API of dataformaat waarvan niet wordt verwacht dat deze enige impact zal hebben op een goede klant. Onbeduidende wijzigingen zijn wijzigingen in witruimte buiten letterlijke talen en de volgorde van velden in een JSON-object.
• Stabiele Interface: een API of gegevensformaat waarvoor brekende en significante wijzigingen zullen worden aangekondigd volgens het onderstaande beleid. Welke interfaces als stabiel worden beschouwd, wordt gedefinieerd in de Stabiele Interfaces verderop in dit document.

Beleid met notificatie

In dit deel wordt bepaald waar en wanneer de beheerders van klanten en consumenten op de hoogte worden gebracht van wijzigingen in een "stabiele interface". Er worden geen garanties gegeven met betrekking tot onstabiele interfaces.

• Verstorende wijzigingen naar stabiele interfaces zullen vooraf naar behoren worden aangekondigd op de relevante mailinglijsten (wikidata-tech, wikidata en pywikibot) en op de Projectchat. De aankondiging zal over het algemeen vier weken van tevoren worden gedaan, maar niet minder dan twee weken voordat de wijziging wordt geïmplementeerd op https://www.wikidata.org/. De wijziging is ten minste twee weken voor implementatie op https://test.wikidata.org/ beschikbaar voor tests. Dergelijke aankondigingen hebben het woord BREAKING in de onderwerpregel.
• Significante wijzigingen in stabiele interfaces zullen worden aangekondigd op de relevante mailinglijsten (wikidata-tech, wikidata en pywikibot) en op de Projectchat. De aankondiging zal over het algemeen ten minste twee weken van tevoren worden gedaan, maar niet minder dan een week nadat de wijziging op https://www.wikidata.org/ is geïmplementeerd. De wijziging is doorgaans ten minste twee weken voor implementatie op https://test.wikidata.org/ beschikbaar voor tests.
• Onbeduidende wijzigingen in stabiele interfaces worden over het algemeen niet aangekondigd.
• Wijzigingen in niet-stabiele interfaces worden mogelijk niet aangekondigd, zelfs niet als ze de werking kunnen verstoren.
• Belangrijke wijzigingen in dit beleid zullen worden aangekondigd op de relevante mailinglijsten (wikidata-tech en wikidata) en op de Projectchat binnen een week nadat de wijziging is aangebracht.

Uitbreidbaarheid

In dit gedeelte wordt uitgelegd op welke manier ons gegevensmodel en onze gegevensindelingen uitbreidbaar zijn. Consumenten moeten rekening houden met deze informatie om rekening te houden met onbekende structuren die ze in de gegevens kunnen tegenkomen.

Het Wikibase Data Model is ontworpen om uitbreidbaar te zijn. Het is met name mogelijk om nieuwe gegevenstypen en nieuwe entiteitstypen te introduceren. Goede klanten en consumenten moeten dus voorbereid zijn om onbekende gegevenstypen en entiteitstypen tegen te komen en deze gracieus te behandelen, op een manier die geschikt is voor het gebruik in kwestie. In veel gevallen is het gepast om dergelijke structuren van het onbekende type eenvoudigweg te negeren.

Evenzo zijn bindingen zoals de JSON-representatie van het Wikibase-gegevensmodel zijn ontworpen om uitbreidbaar te zijn. Datastructuren kunnen op elke syntactisch geschikte plaats worden toegevoegd, zolang ze de betekenis van al bestaande velden of datastructuren niet wijzigen en zolang de toevoeging ervan geen garanties met betrekking tot de bevattende gegevensstructuren breekt. Dit volgt het idee van het Liskov-substitutieprincipe: wat vóór de toevoeging aan een datastructuur was gegarandeerd, moet na de toevoeging nog steeds worden gegarandeerd.

Als er geen expliciete garanties worden gegeven met betrekking tot de structuur en inhoud van een gegevensstructuur, moeten de volgende beginselen leidraad bieden voor de vraag of een wijziging als een brekende wijziging moet worden beschouwd:

In structuren die gebaseerd zijn op lijsten (ook bekend als arrays) en kaarten (ook bekend als hashes of objecten), zoals JSON, wordt het toevoegen van een sleutel aan een kaart niet beschouwd als een brekende verandering, zolang het nieuwe veld de interpretatie van andere velden in de structuur (noch in een omringende structuur) verandert. Het toevoegen van een structuur aan een lijst of set wordt echter als een brekende wijziging beschouwd als het aannames zou breken over het type structuur dat in de lijst te verwachten is, of onder welke voorwaarden een structuur in de lijst zou worden opgenomen.

Volgens afspraak worden lijsten als homogeen beschouwd en mogen zij slechts één soort element bevatten, tenzij anders aangegeven. Het toevoegen van een gegevensstructuur aan een lijst is dus een brekende wijziging als die gegevensstructuur niet compatibel is met het type structuur dat de lijst eerder heeft gedefinieerd of geïmpliceerd moet bevatten.

In een tabellaire gegevensrepresentatie, zoals een relationeel databaseschema, wordt het toevoegen van velden niet beschouwd als een brekende wijziging. Elke wijziging in de interpretatie van een veld, evenals het verwijderen van velden, worden als brekend beschouwd. Wijzigingen in bestaande unieke indexen of primaire sleutels breken wijzigingen; Wijzigingen in andere indexen en de toevoeging van nieuwe indexen zijn geen brekende veranderingen.

In DOM-achtige structuren op basis van geneste getypte elementen met attributen, zoals XML, wordt het toevoegen van een attribuut niet beschouwd als een brekende wijziging, zolang het nieuwe attribuut de interpretatie van andere velden in de structuur (noch in een omringende structuur) verandert. Het toevoegen van een nieuw type element aan een bovenliggend element wordt ook niet als brekend beschouwd als dat bovenliggende element heterogeen is en in wezen als een afbeelding fungeert. Als het bovenliggende element echter wordt gedefinieerd of geïmpliceerd als een homogene lijst van een specifiek soort onderliggend element, wordt het toevoegen van een ander soort element als een brekende wijziging beschouwd.

Voor gegevensindelingen die namespacing toestaan, zoals XML, kunnen namen (kenmerknamen, elementnamen) die behoren tot een naamruimte die niet expliciet wordt genoemd in de specificatie van de gegevensindeling, door consumenten worden genegeerd. Toevoegingen en wijzigingen in gegevensstructuren uit andere naamruimten worden niet beschouwd als brekende wijzigingen.

De volgende wijzigingen zijn daarentegen voorbeelden van brekende wijzigingen, en kunnen dus niet worden gebruikt om een indeling uit te breiden: verwijdering van velden, wijzigingen in het type of formaat van een primitieve waarde, wijzigingen in de interpretatie of rol van een gegevensveld, evenals wijzigingen in het elementtype van een verzameling zoals hierboven beschreven.

Stabiele dataformaten

In dit gedeelte worden de gegevensindelingen weergegeven die we als stabiel beschouwen. Deze gegevensformaten zijn onderworpen aan het bovenstaande meldingsbeleid.

De RDF-mapping van het Wikibase Datamodel, zoals gebruikt in RDF-dumps en in de Linked Data Interface en de Query Service, wordt beschouwd als een stabiel gegevensformaat. Het Wikibase-vocabulaire wordt formeel gedefinieerd door http://wikiba.se/ontology. Eventuele wijzigingen in de structuur of interpretatie van de mapping zijn onderworpen aan het bovenstaande kennisgevingsbeleid. Volgens de algemene principes van RDF wordt aanvullende informatie die op elk moment, op elke locatie, over elk onderwerp wordt geïntroduceerd, niet als een brekende verandering beschouwd.

De JSON-binding van het Wikibase Datamodel zoals gebruikt in JSON-dumps, met de web-API en met de Linked Data Interface, wordt beschouwd als een stabiel gegevensformaat. Eventuele wijzigingen in de structuur of interpretatie van de mapping zijn onderworpen aan het bovenstaande kennisgevingsbeleid. In navolging van het flexibele karakter van JSON wordt het toevoegen van velden aan JSON-objecten niet beschouwd als een brekende verandering. Goede consumenten moeten bereid zijn om dergelijke extra velden te negeren.

Stabiele Publieke API's

In dit gedeelte worden de interfaces vermeld die wij als stabiel beschouwen. Deze interfaces zijn onderworpen aan het bovenstaande meldingsbeleid.

De Wikibase Web API toegankelijk via https://www.wikidata.org/w/api.php wordt beschouwd als een stabiele interface. Wijzigingen in de parameters, bewerking of geretourneerde gegevensstructuur zijn onderworpen aan het bovenstaande meldingsbeleid.

De Linked Data Interface toegankelijk via https://www.wikidata.org/wiki/Special:EntityData en https://www.wikidata.org/entity/... wordt beschouwd als een stabiele interface. Wijzigingen in de parameters, bewerking of geretourneerde gegevensstructuur zijn onderworpen aan het bovenstaande meldingsbeleid.

De Wikidata Query Service toegankelijk via https://query.wikidata.org/ wordt beschouwd als een stabiele interface. Het biedt een volledig SPARQL eindpunt. Wijzigingen in de parameters, bewerking of geretourneerde gegevensstructuur zijn onderworpen aan het bovenstaande meldingsbeleid.

De Wikibase Lua bibliotheek voor klant wiki's wordt beschouwd als een stabiele interface. Wijzigingen in de beschikbare functies, parameters of geretourneerde gegevensstructuren zijn onderworpen aan het bovenstaande meldingsbeleid.

Om een betere gadgetintegratie mogelijk te maken, worden JavaScript-hooks, gedocumenteerd in het hooks-js.md bestand, geleverd samen met Wikibase-broncode, als stabiel beschouwd.

We erkennen dat hulpmiddelen van derden op Cloud VPS en Toolforge kan vertrouwen op de Wikibase database schema. Daarom zijn wijzigingen in de beschikbare tabellen en velden onderworpen aan het bovenstaande meldingsbeleid. Houd er echter rekening mee dat het databaseschema niet is ontworpen als een openbare API en dat er minder aandacht wordt besteed aan achterwaartse compatibiliteit.

Onstabiele Interfaces

In dit gedeelte worden enkele interfaces vermeld die we nu niet als stabiel beschouwen en die daarom zonder kennisgeving op incompatibele manieren kunnen worden gewijzigd.

MediaWiki XML Dumps worden niet beschouwd als een stabiele interface. MediaWiki XML-dumps bevatten de onbewerkte gegevens van paginarevisies in hun interne representatie. De interne vertegenwoordiging van Wikibase-entiteiten is geen stabiele interface. Het is in het verleden aanzienlijk veranderd en het kan in de toekomst opnieuw veranderen. Verschillende representaties van Wikibase-inhoud kunnen aanwezig zijn in dezelfde XML-dump.

Ruwe revisie-inhoud zoals geretourneerd door de MediaWiki core API wordt niet beschouwd als een stabiele interface, omdat het de interne representatie van de inhoud gebruikt, net als de XML-dumps. Onbewerkte revisie-inhoud wordt geretourneerd vanuit API-query's zoals api.php?action=query&prop=revisions&titles=Q42&rvprop=timestamp|user|comment|content.

Wikibase PHP code wordt niet beschouwd als een stabiele interface. Hoewel het Wikibase-project nu officiële releases biedt, ontvangt wikidata.org nog steeds een lopende implementatie van Wikibase-code. Daarom is er geen moment waarop een bepaalde PHP-klasse of -interface kan worden verondersteld stabiel te blijven.

Wikibase JavaScript-code wordt niet beschouwd als een stabiele interface. Hoewel het Wikibase-project nu officiële releases biedt, ontvangt wikidata.org nog steeds een lopende implementatie van Wikibase-code. Daarom is er geen moment waarop kan worden aangenomen dat JavaScript-code stabiel blijft. Dit betekent dat Gadgets er niet op kunnen vertrouwen dat de JavaScript-code stabiel blijft.

De HTML DOM structuur gegenereerd door Wikibase wordt niet beschouwd als een stabiele interface. Dit betekent dat Gadgets er niet op kunnen vertrouwen dat de DOM-structuur stabiel blijft.

Outlook

Deze sectie bevat informatie over verbeteringen die zijn gepland of overwogen worden.

De JSON-binding moet worden voorzien van een versie-aanduiding (met behulp van de semantische versiebeheer conventie), zodat consumenten weten welke structuren ze kunnen verwachten en hoe ze deze moeten interpreteren. Zie phab:T92961.

Wikibase JavaScript code moet stabiele interfaces aangeven die met vertrouwen door gadgets kunnen worden gebruikt.

Wikibase zou een aantal basisgaranties moeten bieden over de HTML DOM structuur die het genereert, zodat Gadgets vol vertrouwen kunnen communiceren met de DOM.

Voor installaties van derden heeft Wikibase nu reguliere releases gekoppeld aan MediaWiki releases. Wikidata zal echter lopende deployments van de nieuwste ontwikkelingsversie blijven gebruiken.

Geschiedenis

In dit gedeelte worden eerdere en geplande wijzigingen weergegeven, met de nieuwste bovenaan. De lijst met wijzigingen uit het verleden vóór de implementatie van dit beleid kan onvolledig zijn. Elke wijziging moet worden vermeld met de datum van aankondiging en de datum van inzet, idealiter vergezeld van een link naar de aankondiging en eventuele relevante tickets.

• 2024-02-19: [Aankondiging belangrijke wijziging] Aankomende wijzigingen in Wikibase API-modules: toevoeging van nieuwe parameters. aangekondigd 2024-02-19
• 2024-01-24: [Aankondiging wijziging] Lege betekenissen / formulieren lijsten presentatie in lexeem dumps. Aangekondigd op 24-01-2024, ingevoerd op 08-01-2024
• 2023-05-18: [Aankondiging wijziging] entiteitslabels toegevoegd aan verwerkte bewerkingssamenvattingen in API-aanvragen.Aangekondigd 2023-05-04
• 2023-05-18: [Aankondiging wijziging] Inconsistenties in het antwoord van de API-querymodule 'list=wbsubscribers'. Aangekondigd 2023-05-04
• 2023-05-17: [Aankondiging wijziging] Wijzigingen in de wblistentityusage API-module. Aangekondigd 2023-05-03
• 2022-07-26: Nieuwe zoekprofiel profile parameter in Wikidata’s wbsearchentities API module. Aangekondigd 2022-07-26
• 2021-09-06: Wijziging in de web-API : normalisatie van gegevenswaarden bij het opslaan van een bewerking. Aangekondigd 2021-08-23
• 2021-05-27: Wikidata formulieren zonder statements gebruiken lege JSON-matrix in plaats van een leeg JSON-object. Aangekondigd 2021-05-27
• 2021-03-03: Wijziging in de web-API : wbeditentity-antwoord maakt nu gebruik van standaardserialisatie. (Wordt alleen onderbroken voor MediaInfo-entiteiten, wat belangrijk is voor sommige andere entiteitstypen.) Aangekondigd 2021-02-08
• 2020-08-05: Wijziging in de web-API: het verwijderen van het gedrag van speciale paginatermen op repo-wiki's, gebruik in plaats daarvan entityterms. Aangekondigd 2020-07-15
• 2020-04-16: Lege node verwijdering in WDQS en Wikibase RDF-model. Aangekondigd 2020-04-16
• 2019-05-06: Wijziging in de web-API van de extensie WikibaseQualityConstraints: standaardwaarde van status parameter bevat nu de nieuwe "suggestie" voorwaarde status. Aangekondigd 2019-04-17
• 2019-04-30: wijziging in de JSON-serialisatie: lege containers in JSON-uitgangen worden geserialiseerd als leeg object in plaats van leegarray. Aangekondigd 2019-04-02
• 2018-11-16: Breaking change to RDF representation: the "beta" in ontology prefix is dropped. Aangekondigd 2018-10-17
• 2018-02-26: Breaking change to the web API of the WikibaseQualityConstraints extension: default value of status parameter is changed. Aangekondigd 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. Aangekondigd 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. Aangekondigd 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. Aangekondigd 2016-11-04
• 2015-09-09: Breaking change to the XML representation of API output. Aangekondigd 2015-08-27
• 2015-06-15: Breaking change to the JSON serialization, replacing type:claim with type:statement. Aangekondigd 2015-06-15
• 2014-08-22: Breaking change to Special:Export to use the same JSON output as the web API. Aangekondigd 2014-08-15
• 2013-09-10: Breaking change to the web API output: Q-IDs are now upper-case. Aangekondigd 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. Aangekondigd 2013-06-16.