Commons:Strukturierte Daten/Stabile Schnittstellenpolitik

Strukturiertes Commons

Über Strukturiertes Commons

Beteilige Dich

GLAM und Kultur

SPARQL

Modellbildung

Diskussion

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

Diese Seite dokumentiert einen Entwurf der operativen Politik von commons.wikimedia.org. Es handelt sich um eine Absichtserklärung des Entwicklerteams, das für die Entwicklung der WikibaseMediaInfo-Software verantwortlich ist.

Stabile öffentliche Schnittstellen für den Datenzugang sind ein wesentlicher Bestandteil jedes öffentlichen Wissensspeichers. Diese stabile Schnittstellenpolitik legt fest, welche Garantien das Entwicklerteam der sturukturierten Daten für die Stabilität der Datenformate von WikibaseMediaInfo, wie sie auf commons.wikimedia.org bereitgestellt werden, gibt und welche nicht.

Definitionen

In diesem Abschnitt werden einige wichtige Begriffe definiert, die in diesem Dokument verwendet werden.

• Consumer: Software, die von Wikimedia Commons empfangene Daten liest und interpretiert.
• Client: Software, die das öffentliche Wikimedia Commons aufruft. Clients sind typischerweise auch Consumer von Daten.
• Konformer Client/Consumer: Ein Client oder Consumer, der die Spezifikation der zugrunde liegenden Formate und Protokolle einhält, die er verwendet. Beispielsweise entspricht ein konformer Consumer, der JSON-Daten liest, der JSON-Spezifikation und akzeptiert jede von der JSON-Spezifikation (RFC 7159) zugelassene Kodierung. Ein konformer Client, der eine Web-API verwendet, entspricht der HTTP-Spezifikation usw.
• Gut funktionierender Client/Consumer: Ein (konformer) Client oder Consumer, der auf eine robuste und aufwärtskompatible Weise implementiert ist, insbesondere unter Berücksichtigung der in diesem Dokument genannten Garantien und Einschränkungen. Ein gut funktionierender Client wird beispielsweise nicht abstürzen, wenn er auf einen neuen Datentyp trifft.
• Breaking Change: Eine Änderung an einem Datenformat, die zuvor gegebene oder allgemein angenommene Garantien verletzt. Zu Breaking Changes gehören das Entfernen von Datenfeldern und Änderungen an der Interpretation oder dem Format von Datenfeldern.
• Wesentliche Änderung: Eine Änderung an einem Datenformat, die für Clients oder Consumer von Vorteil wäre, die aber einen gut funktionierenden Client oder Consumer nicht beeinträchtigt. Zu den wesentlichen Änderungen zählen insbesondere Ergänzungen, wie die Einführung neuer Datentypen oder Entitätstypen oder die Einbeziehung zusätzlicher Informationen in die Datenausgabe. Siehe Erweiterbarkeit weiter unten.
• Unwesentliche Änderung: Eine Änderung an einem Datenformat, die voraussichtlich keine Auswirkungen auf einen gut funktionierenden Client hat. Zu den unwesentlichen Änderungen zählen Änderungen an Leerzeichen außerhalb von Literalen sowie die Reihenfolge der Felder in einem JSON-Objekt.
• Stabile Schnittstelle: Ein Datenformat, für das Breaking Changes und wesentliche Änderungen gemäß der folgenden Richtlinie angekündigt werden. Welche Schnittstellen als stabil gelten, wird weiter unten in diesem Dokument in Stabile Schnittstellen definiert.

Benachrichtigungsrichtlinie

Dieser Abschnitt definiert, wo und wann die Betreiber von Clients und Consumern über Änderungen an einer stabilen Schnittstelle informiert werden. Für instabile Schnittstellen werden keine Garantien übernommen.

• Breaking Changes an stabilen Schnittstellen werden rechtzeitig im Voraus auf den entsprechenden Mailinglisten (wikitech-l, commons-l und pywikibot) und im Technik-Bereich der Village Pump angekündigt. Die Ankündigung erfolgt in der Regel vier Wochen vorher, jedoch nicht weniger als zwei Wochen, bevor die Änderung auf https://commons.wikimedia.org/ umgesetzt wird. Solche Ankündigungen enthalten das Wort BREAKING in der Betreffzeile.
• Wesentliche Änderungen an stabilen Schnittstellen werden auf den entsprechenden Mailinglisten (wikitech-l, commons-l und pywikibot) und im Technik-Bereich der Village Pump angekündigt. Die Ankündigung erfolgt in der Regel mindestens zwei Wochen vorher, jedoch nicht weniger als eine Woche, nachdem die Änderung auf https://commons.wikimedia.org/ umgesetzt wurde.
• Unwesentliche Änderungen an stabilen Schnittstellen werden grundsätzlich nicht angekündigt.
• Änderungen an nicht stabilen Schnittstellen werden möglicherweise nicht angekündigt, auch wenn es sich um Breaking Changes handelt.
• Wesentliche Änderungen an dieser Richtlinie werden auf den entsprechenden Mailinglisten (wikitech-l, commons-l und pywikibot) und im Technik-Bereich der Village Pump mindestens eine Woche vorher angekündigt, bevor die Änderung vorgenommen wird.

Erweiterbarkeit

In diesem Abschnitt wird erläutert, auf welche Weise unser Datenmodell und unsere Datenformate erweiterbar sind. Die Nutzer sollten diese Informationen berücksichtigen, um unbekannte Strukturen, auf die sie in den Daten stoßen könnten, berücksichtigen zu können.

Das Wikibase-Datenmodell ist so konzipiert, dass es erweiterbar ist. Insbesondere ist es möglich, neue Datentypen und neue Entitätstypen einzuführen. Gut funktionierende Clients und Consumer sollten daher darauf vorbereitet sein, auf unbekannte Datentypen und Entitätstypen zu stoßen und diese auf eine für den jeweiligen Einsatzzweck angemessene Weise zu handhaben. In vielen Fällen ist es angebracht, solche Strukturen unbekannten Typs einfach zu ignorieren.

Ebenso sind Bindungen wie die JSON-Darstellung des Wikibase-Datenmodells so konzipiert, dass sie erweiterbar sind. Datenstrukturen können an jeder syntaktisch geeigneten Stelle hinzugefügt werden, solange sie die Bedeutung bereits vorhandener Felder oder Datenstrukturen nicht ändern und solange ihre Hinzufügung keine Garantien in Bezug auf die enthaltenen Datenstrukturen verletzt. Dies folgt der Idee des Liskovschen Substitutionsprinzips: Was vor der Hinzufügung über eine Datenstruktur garantiert war, sollte auch nach der Hinzufügung garantiert sein.

Wenn keine expliziten Garantien hinsichtlich der Struktur und des Inhalts einer Datenstruktur gegeben werden, sollten die folgenden Grundsätze als Orientierung dafür dienen, ob eine Änderung als Breaking Change betrachtet werden sollte:

• In Strukturen, die auf Listen (auch Arrays genannt) und Maps (auch Hashes oder Objekte genannt) basieren, wie etwa JSON, wird das Hinzufügen eines Schlüssels zu einer Map nicht als Breaking Change betrachtet, solange das neue Feld die Interpretation anderer Felder in der Struktur (oder in einer umgebenden Struktur) nicht ändert. Das Hinzufügen einer Struktur zu einer Liste oder einem Set wird jedoch als Breaking Change betrachtet, wenn dadurch Annahmen über den in der Liste zu erwartenden Strukturtyp oder die Bedingungen, unter denen eine Struktur in die Liste aufgenommen würde, gestört würden.
• Listen werden per Konvention als homogen betrachtet und sollten, sofern nicht anders angegeben, nur einen Elementtyp enthalten. Das Hinzufügen einer Datenstruktur zu einer Liste ist daher ein Breaking Change, wenn diese Datenstruktur nicht mit dem Strukturtyp kompatibel ist, den die Liste zuvor definiert hat oder enthalten sollte.
• In einer tabellarischen Datendarstellung, wie etwa einem relationalen Datenbankschema, wird das Hinzufügen von Feldern nicht als Breaking Change betrachtet. Jede Änderung an der Interpretation eines Felds sowie das Entfernen von Feldern werden als Breaking Change betrachtet. Änderungen an vorhandenen eindeutigen Indizes oder Primärschlüsseln sind Breaking Changes; Änderungen an anderen Indizes sowie das Hinzufügen neuer Indizes sind keine Breaking Changes.
• In DOM-ähnlichen Strukturen, die auf verschachtelten typisierten Elementen mit Attributen basieren, wie es bei XML der Fall ist, wird das Hinzufügen eines Attributs nicht als Breaking Change angesehen, solange das neue Attribut die Interpretation anderer Felder in der Struktur (oder in einer umgebenden Struktur) nicht ändert. Das Hinzufügen eines neuen Elementtyps zu einem übergeordneten Element wird ebenfalls nicht als Breaking Change angesehen, wenn dieses übergeordnete Element heterogen ist und sich im Wesentlichen wie eine Map verhält. Wenn das übergeordnete Element jedoch als homogene Liste eines bestimmten Typs von untergeordneten Elementen definiert oder impliziert ist, wird das Hinzufügen eines anderen Elementtyps als Breaking Change angesehen.
• Bei Datenformaten, die Namensräume zulassen, wie XML, können Namen (Attributnamen, Elementnamen), die zu einem in der Spezifikation des Datenformats nicht explizit erwähnten Namensraum gehören, von Consumern ignoriert werden. Hinzufügungen und Änderungen an Datenstrukturen aus anderen Namensräumen gelten nicht als Breaking Changes.
• Im Gegensatz dazu sind folgende Änderungen Beispiele für Breaking Changes und können somit nicht zur Erweiterung eines Formats verwendet werden: Entfernen von Feldern, Änderungen am Typ oder Format eines primitiven Werts, Änderungen an der Interpretation oder Rolle eines Datenfelds sowie Änderungen am Elementtyp einer Sammlung, wie oben beschrieben.

Stabile Datenformate

In diesem Abschnitt sind die Datenformate aufgeführt, die wir als stabil betrachten. Diese Datenformate unterliegen der oben genannten Benachrichtigungsrichtlinie.

Das RDF-Mapping des WikibaseMediaInfo-Datenmodells, wie es in RDF-Dumps sowie in der Linked-Data-Schnittstelle verwendet wird, wird als stabiles Datenformat betrachtet. Alle Änderungen an der Struktur oder Interpretation des Mappings unterliegen der oben genannten Benachrichtigungsrichtlinie. Gemäß den allgemeinen Grundsätzen von RDF gelten zusätzliche Informationen, die zu irgendeinem Zeitpunkt, an irgendeinem Ort und zu irgendeinem Subjekt hinzugefügt werden, nicht als Breaking Change.

Die JSON-Bindung des WikibaseMediaInfo-Datenmodells, wie sie in JSON-Dumps, mit der Web-API und mit der Linked-Data-Schnittstelle verwendet wird, wird als stabiles Datenformat betrachtet. Alle Änderungen an der Struktur oder Interpretation der Zuordnung unterliegen der oben genannten Benachrichtigungsrichtlinie. Aufgrund der flexiblen Natur von JSON wird das Hinzufügen von Feldern zu JSON-Objekten nicht als Breaking Change betrachtet. Gut funktionierende Consumer sollten darauf vorbereitet sein, solche zusätzlichen Felder zu ignorieren.

Stabile öffentliche APIs

In diesem Abschnitt sind die Schnittstellen aufgeführt, die wir als stabil betrachten. Diese Schnittstellen unterliegen der oben genannten Benachrichtigungsrichtlinie.

Die über https://commons.wikimedia.org/w/api.php erreichbare Wikibase Web-API gilt als stabile Schnittstelle. Änderungen an den Parametern, Operationen oder der zurückgegebenen Datenstruktur unterliegen der Benachrichtigungsrichtlinie.

Die über https://commons.wikimedia.org/wiki/Special:EntityData und https://commons.wikimedia.org/entity/... erreichbare Linked-Data-Schnittstelle gilt als stabile Schnittstelle. Änderungen an den Parametern, Operationen oder der zurückgegebenen Datenstruktur unterliegen der oben genannten Benachrichtigungsrichtlinie.

Der über https://wcqs-beta.wmflabs.org/ erreichbare Wikimedia Commons Query Service befindet sich in der Betaphase und sollte nicht als stabile Schnittstelle betrachtet werden. Er bietet einen vollständigen SPARQL-Endpunkt. Während der Betaphase unterliegt er nicht der oben genannten Benachrichtigungsrichtlinie, kann aber als Dienst bereitgestellt werden.

Um eine bessere Integration von Helferleins zu ermöglichen, gelten die in der zusammen mit dem Wikibase-Quellcode gelieferten Datei hooks-js.md dokumentierten JavaScript-Hooks als stabil.

Wir erkennen an, dass Werkzeuge von Drittanbietern auf Cloud VPS und Toolforge auf das Wikibase-Datenbankschema angewiesen sein können. Während Änderungen an WikibaseMediainfo, die verfügbare Tabellen und Felder betreffen, der oben genannten Benachrichtigungsrichtlinie unterliegen, unterliegen Änderungen an Wikibase selbst der Stabilen Schnittstellenpolitik von Wikidata. Beachte jedoch, dass das Datenbankschema nicht als öffentliche API konzipiert ist und der Abwärtskompatibilität weniger Beachtung geschenkt wird.

Instabile Schnittstellen

In diesem Abschnitt sind einige Schnittstellen aufgeführt, die wir derzeit nicht als stabil betrachten und bei denen es daher ohne Vorankündigung zu inkompatiblen Änderungen kommen kann.

MediaWiki XML-Dumps werden nicht als stabile Schnittstelle betrachtet. MediaWiki XML-Dumps enthalten die Rohdaten von Seitenversionen in ihrer internen Darstellung. Die interne Darstellung von WikibaseMediaInfo-Entitäten ist keine stabile Schnittstelle. Sie hat sich in der Vergangenheit erheblich geändert und kann sich in Zukunft erneut ändern. Im selben XML-Dump können mehrere verschiedene Darstellungen von WikibaseMediaInfo-Inhalten vorhanden sein.

Wikibase + WikibaseMediaInfo PHP-Code wird nicht als stabile Schnittstelle betrachtet. Obwohl das Wikibase-Projekt jetzt offizielle Veröffentlichungen bereitstellt, erhält commons.wikimedia.org weiterhin fortlaufend Wikibase- und WikibaseMediaInfo-Code. Daher gibt es keinen Zeitpunkt, an dem davon ausgegangen werden kann, dass eine bestimmte PHP-Klasse oder -Schnittstelle stabil bleibt.

Wikibase + WikibaseMediaInfo JavaScript-Code wird nicht als stabile Schnittstelle betrachtet. Obwohl das Wikibase-Projekt jetzt offizielle Veröffentlichungen bereitstellt, erhält commons.wikimedia.org weiterhin fortlaufend Wikibase- und WikibaseMediaInfo-Code. Daher gibt es keinen Zeitpunkt, an dem davon ausgegangen werden kann, dass JavaScript-Code stabil bleibt. Das bedeutet, dass Helferleins sich nicht darauf verlassen können, dass der JavaScript-Code stabil bleibt.

Die von WikibaseMediaInfo generierte HTML-DOM-Struktur wird nicht als stabile Schnittstelle betrachtet. Das bedeutet, dass Helferleins sich nicht darauf verlassen können, dass die DOM-Struktur stabil bleibt.

Ausblick

Dieser Abschnitt bietet Informationen über Verbesserungen, die für die Zukunft geplant sind oder in Betracht gezogen werden.

Geschichte

In diesem Abschnitt sind vergangene und geplante Breaking Changes aufgeführt. Die Liste vergangener Änderungen vor der Implementierung dieser Richtlinie ist möglicherweise unvollständig. Jede Änderung sollte mit dem Datum der Ankündigung und dem Datum der Einführung aufgelistet werden, idealerweise zusammen mit einem Link zur Ankündigung und allen relevanten Tickets.