Commons:Structured data/Stable Interface Policy/nl

Structuur

Over

Doe mee

GLAM en cultuur

SPARQL

Modellen

Overleg

About Structured Commons • Why we work on this • Structured data on other projects • Press and presentations • Features glossary • Project glossary • Stable Interface Policy • Contact

Deze pagina documenteert een concept operationeel beleid van commons.wikimedia.org. Het is een intentieverklaring van het technische team dat verantwoordelijk is voor de ontwikkeling van de WikibaseMediaInfo-software.

Stabiele openbare interfaces voor gegevenstoegang zijn een cruciaal onderdeel van elke openbare repository. Dit beleid definieert welke garanties wel en niet worden gegeven door het Structured Data engineering team met betrekking tot de stabiliteit van dataformaten geleverd door WikibaseMediaInfo zoals geïmplementeerd op commons.wikimedia.org.

Definities

In dit gedeelte worden enkele cruciale termen in dit document gedefinieerd.

• 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 zal bijvoorbeeld niet stuk lopen 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 wijziging: een wijziging van een gegevensformaat die voor cliënten of consumenten voordelig zou zijn om zich aan te passen, maar die een zich goed gedragen klant of consument niet zal verstoren. Er zijn met name belangrijke wijzigingen met toevoegingen, zoals de invoering van nieuwe gegevenstypen of entiteitstypen, of het opnemen van aanvullende informatie in de gegevensuitgang. Zie hieronder Uitbreidbaarheid.
• Kleine wijziging: een wijziging in een API of dataformaat waarvan niet wordt verwacht dat deze enige impact zal hebben op een goede klant. Dit zijn wijzigingen in witruimte buiten letterlijke talen als 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 in stabiele interfaces zullen van tevoren naar behoren worden aangekondigd op de relevante maillijsten (wikitech, commons-l en pywikibot) en op de Technische sectie van de Kroeg. De aankondiging wordt over het algemeen vier weken van tevoren gedaan, maar niet minder dan twee weken voordat de wijziging wordt geïmplementeerd op https://commons.wikimedia.org/. Dergelijke aankondigingen hebben het woord BREAKING in de onderwerpregel.
• Significante wijzigingen in stabiele interfaces zullen worden aangekondigd op de relevante maillijsten (wikitech, commons-l en pywikibot) en op de Technische sectie van de Kroeg. De aankondiging wordt over het algemeen ten minste twee weken van tevoren gedaan, maar niet minder dan een week nadat de wijziging op https://commons.wikimedia.org/ is geïmplementeerd.
• Kleine 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 maillijsten (wikitech, commons-l en pywikibot) en op de Projectchat Kroeg 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 Datamodel is ontworpen om uitbreidbaar te zijn. In het bijzonder is het mogelijk om nieuwe gegevenstypen en nieuwe entiteitstypen te introduceren. 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 dat voorhanden is. In veel gevallen is het gepast om dergelijke structuren van een onbekend type gewoon 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 ze slechts één soort element bevatten, tenzij anders aangegeven. Het toevoegen van een gegevensstructuur aan een lijst is dus een belangrijke wijziging als die gegevensstructuur niet compatibel is met het type structuur dat de lijst eerder was gedefinieerd of geïmpliceerd bevatte.
• 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 verstorende 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 verstorend 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 verstorende wijziging beschouwd.
• Voor gegevensindelingen die spaties in de naam toestaan, zoals XML, kunnen namen (attribuutnamen, elementnamen) die behoren tot een namespace die niet expliciet wordt genoemd in de specificatie van het gegevensformaat, worden genegeerd door consumenten. Het toevoegen en wijzigen van gegevensstructuren vanuit andere namespaces wordt niet beschouwd als wijzigingen die verstorend zijn.
• De volgende wijzigingen zijn daarentegen voorbeelden van verstorende wijzigingen (breaking changes), en kunnen dus niet worden gebruikt om een formaat 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-koppeling van het WikibaseMediaInfo Datamodel, zoals gebruikt in RDF-dumps en in de Linked Data Interface, wordt beschouwd als een stabiel gegevensformaat. Eventuele wijzigingen in de structuur of interpretatie van de koppeling zijn onderworpen aan het bovenstaande kennisgevingsbeleid. Volgens de algemene principes van RDF wordt aanvullende informatie die op elk moment, op elke locatie en over elk onderwerp wordt geïntroduceerd, niet beschouwd als een verstorende wijziging.

De JSON-binding van het WikibaseMediaInfo 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 koppeling zijn onderworpen aan het bovenstaande kennisgevingsbeleid. In navolging van de flexibele aard van JSON wordt het toevoegen van velden aan JSON-objecten niet beschouwd als een verstorende wijziging. Consumenten die zich goed voorbereiden, moeten bereid zijn 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 die via https://commons.wikimedia.org/w/api.php toegankelijk is, wordt beschouwd als een stabiele interface. Veranderingen van de parameters, de werking of de teruggegeven gegevens zijn onderworpen aan dit beleid.

De Linked Data Interface die via https://commons.wikimedia.org/wiki/Special:EntityData en https://commons.wikimedia.org/entity/... toegankelijk is, wordt beschouwd als een stabiele interface. Veranderingen van de parameters, de werking of de teruggegeven gegevens zijn onderworpen aan het bovenstaande kennisgevingsbeleid.

De Wikimedia Commons Query Service is toegankelijk via https://wcqs-beta.wmflabs.org/ zich in een bèta bevindt en niet als een stabiele interface moet worden beschouwd. Het biedt een volledige SPARQL-eindpunt. Zolang het in bèta is, is het niet onderworpen aan het bovenstaande meldingen-beleid, maar kan het als service worden verstrekt.

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 kunnen vertrouwen op het Wikibase database-schema. Hoewel wijzigingen in WikibaseMediainfo die invloed hebben op beschikbare tabellen en velden onderworpen zijn aan het bovenstaande kennisgevingsbeleid; zijn wijzigingen in WikiBase zelf onderworpen aan het Wikidata stabiele interfacebeleid. Merk echter op dat het database-schema niet is ontworpen om een openbare API te zijn en er minder aandacht wordt besteed aan compatibiliteit met oudere versies.

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 grondgegevens van paginaherziening in hun interne weergave. De interne vertegenwoordiging van WikiBaseMediaInfo-entiteiten is geen stabiele interface. Het is in het verleden aanzienlijk veranderd en kan in de toekomst ook veranderen. Verschillende verschillende weergaven van WikibaseMediaInfo-inhoud kunnen in dezelfde XML-dump aanwezig zijn.

Wikibase + WikibaseMediaInfo PHP-code worden niet beschouwd als een stabiele interface. Hoewel het Wikibase-project nu officiële releases biedt, krijgt commons.wikimedia.org nog steeds uitrollende implementatie van Wikibase & WikibaseMediaInfo-code. Daarom is er geen tijdstip waarop kan worden aangenomen dat een bepaalde PHP-klasse of interface stabiel blijft.

Wikibase + WikibaseMediaInfo JavaScript code wordt niet beschouwd als een stabiele interface. Hoewel het Wikibase-project nu officiële releases biedt, ontvangt commons.wikimedia.org nog steeds doorlopende implementatie van Wikibase- en WikibaseMediaInfo-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 WikibaseMediaInfo 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.

Geschiedenis

In dit gedeelte worden eerdere en geplande wijzigingen weergegeven. 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.