Commons:Données structurées/Politique pour une interface stable

Données structurées & Commons

À propos

Participer

GLAM et culture

SPARQL

Modéliser

Forum

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

Cette page contient une version en cours de construction d'une politique opérationnelle de commons.wikimedia.org. Il s'agit d'une déclaration d'intention rédigée par l'équipe de conception responsable du développement du logiciel WikibaseMediaInfo.

Des interfaces publiques stables pour l'accès aux données sont un composant crucial de tout dépôt de connaissances public. Cette politique pour une interface stable définit les garanties qui sont (ou non) fournies par l'équipe de conception des données structurées concernant la stabilité des formats de données fournis par WikibaseMediaInfo tel qu'il est déployé sur commons.wikimedia.org.

Définitions

Cette section définit quelques termes cruciaux utilisés dans le présent document.

• Consommateur : logiciel qui lit et interprète les données reçues de Wikimedia Commons.
• Client : logiciel qui effectue des appels publics sur Wikimedia Commons. Les clients sont habituellement également des consommateurs de données.
• Client/consommateur conforme : un client ou consommateur conforme aux spécifications des formats et protocoles sous-jacents qu'il utilise. Par exemple, un consommateur conforme qui lit les données JSON est conforme à la spécification JSON et accepte tout codage autorisé par la spécification JSON (RFC 7159). Un client conforme utilisant une API web se conformera aux spécifications HTTP, etc.
• Client/consommateur bien élevé : un client ou un consommateur (compatible) qui est mis en œuvre d'une manière robuste et selon une compatibilité ascendente, en tenant compte en particulier des garanties et des limitations listées dans le présent document. Par exemple, un client bien élevé ne va pas planter lorsqu'il rencontre un nouveau type de données.
• Modification radicale : une modification dans le format des données qui viole le contrat anciennement annoncé ou espéré. Les modifications radicales comprennent la suppression de champs de données et les modifications dans l'interprétation ou dans le format des champs de données.
• Modification significative : une modification d'un format de données à laquelle l'adaptation des clients et des consommateurs leur serait bénéfique, mais qui ne fait pas planter un client ou un consommateur bien élevé. Les modifications significatives comprennent en particulier les ajouts, tels que l'introduction de nouveaux types de données ou d'entités, ou l'inclusion d'informations additionnelles dans les données émises. Voir extensibilité ci-dessous.
• Modifications mineures : modification d'un format de données qui ne devrait avoir aucun impact sur un client bien élevé. Les modifications mineures comprennent les modifications sur les espaces situés hors des valeurs littérales ainsi que sur l'ordre des champs dans un objet JSON.
• Interface stable : format de données pour lequel les modifications radicales ou significatives seront annoncées en vertu de la politique ci-dessous. Les interfaces qui sont considérées comme étant stables sont définies au chapitre Interfaces stables plus loin dans ce document.

Politique de notifications

Cette section définit où et quand les opérateurs des clients et des consommateurs seront notifiés quant aux modifications sur une interface stable. Aucune garantie n'est apportée quant aux interfaces non stables.

• Les modifications radicales apportées aux interfaces stables seront dûment annoncées à l'avance sur les listes de diffusion correspondantes (wikitech-l, commons-l et pywikibot) et sur la section technique du Bistro. Les annonces seront généralement réalisées quatre semaines à l'avance, et jamais moins de deux semaines avant que la modification ne soit déployée sur https://commons.wikimedia.org/. De telles annonces comporteront le mot BREAKING dans leur objet.
• Les modifications significatives apportées aux interfaces stables seront annoncées sur les listes de diffusion correspondantes (wikitech-l, commons-l et pywikibot) et sur la section technique du Bistro. L'annonce sera généralement réalisée au moins deux semaines à l'avance, et jamais moins d'une semaine après que la modification n'aie été déployée sur https://commons.wikimedia.org/.
• Les modifications mineures apportées aux interfaces stables ne seront généralement pas annoncées.
• Les modifications apportées aux interfaces non-stables pourront ne pas être annoncées, même s'il s'agit de modifications radicales.
• Les modifications importantes apportées à la présente politique seront annoncées sur les listes de diffusion appropriées (wikitech-l, commons-l et pywikibot) et sur la section technique du Bistro dans la semaine précédent la mise en œuvre de la modification.

Extensibilité

Cette section explique de quelle manière notre modèle de données et nos formats de données sont extensibles. Les consommateurs devraient prendre en compte ces informations afin de gérer les structures inconnues qu'ils pourraient rencontrer dans les données.

LeWikibase est conçu pour être extensible. En particulier, il est possible d'introduire de nouveaux types de données et de types d'entités. Les clients et les consommateurs bien élevés devraient donc s'attendre à trouver des types de données ou d'entités inconnus et à les gérer sans provoquer d'erreur, d'une manière appropriée pour les garder accessibles. Dans de nombreux cas, le mieux est de simplement ignorer de telles structures d'un type inconnu.

Similarly, bindings such as the JSON representation of 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 the Liskov 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 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.

Formats de données stables

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

The RDF mapping of the WikibaseMediaInfo Data Model, as used in RDF dumps as well as in 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. 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 WikibaseMediaInfo 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.

APIs publiques stables

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

The Wikibase Web API accessible via https://commons.wikimedia.org/w/api.php is considered a stable interface. Changes to the parameters, operation, or returned data structure are subject to the notification policy.

The Linked Data Interface accessible via https://commons.wikimedia.org/wiki/Special:EntityData and https://commons.wikimedia.org/entity/... is considered a stable interface. Changes to the parameters, operation, or returned data structure are subject to the above notification policy.

The Wikimedia Commons Query Service accessible via https://wcqs-beta.wmflabs.org/ is in a beta and should not be considered a stable interface. It provides a full SPARQL endpoint. Whilst in beta, it is not subject to the above notification policy but may be provided as a courtesy.

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. Whilst changes to WikibaseMediainfo that impact available tables and fields are subject to the above notification policy; changes to Wikibase itself are subject to the Wikidata stable interface policy. However, note that the database schema is not designed to be a public API, and less consideration is given to backwards compatibility.

Interfaces instables

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 WikibaseMediaInfo 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 WikibaseMediaInfo content may be present in the same XML dump.

Wikibase + WikibaseMediaInfo PHP code is not considered a stable interface. Although the Wikibase project now provides official releases, commons.wikimedia.org still receives rolling deployment of Wikibase & WikibaseMediaInfo code. Therefore there is no point in time at which any given PHP class or interface can be assumed to remain stable.

Wikibase + WikibaseMediaInfo JavaScript code is not considered a stable interface. Although the Wikibase project now provides official releases, commons.wikimedia.org still receives rolling deployment of Wikibase & WikibaseMediaInfo 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 WikibaseMediaInfo 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.

History

This section lists past and scheduled breaking changes. 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.