Wikidata:‎‎安定したインターフェイスの方針

データアクセスのための安定した公共のインターフェイスは、公共の知識の集積所の重要な構成要素です。 この安定したインターフェースの方針は、www.wikidata.orgで展開されたウィキベースによって提供されるデータ形式とAPIの安定性に関してウィキデータ開発チームによって保証されることと保証されないことを定義します。

定義

‎この節では、この文書で使用される重要な用語をいくつか定義します。‎

• 消費者:‎‎ウィキデータから受け取ったデータを読み取り、解釈するソフトウェア。‎
• クライアント:公開ウィキデータAPIを呼び出すソフトウェア。クライアントは通常、データの「消費者」でもあります。‎
• 準拠クライアント/消費者:クライアントまたは消費者が使用する基本の形式とプロトコルの仕様に準拠している。たとえば、JSONデータを読み取る準拠消費者はJSON仕様に準拠しており、JSON仕様で許可されている任意の符号化を受け入れます(RFC 7159)。Web APIを使用する準拠クライアントは、HTTP仕様などに準拠します。‎
• 行儀のよいクライアント/消費者: 堅牢かつ前方互換な方法で、特にこの文書で述べられた保証と制限を考慮に入れて実装された（準拠）クライアントまたは消費者。例えば、行儀のよいクライアントは新しいデータ型に出くわしたときに壊れません。
• 破壊的変更:以前提供もしくは広く仮定されていた保証を破るAPIやデータ形式への変更。破壊的変更には、API機能やパラメータやデータフィールドの除去、およびパラメータやデータフィールドの解釈や形式への変更が含まれます。
• 重大な変更:適応するとクライアントにとって有益であるが、行儀のよいクライアントや消費者を壊さないAPIまたはデータ形式への変更。重大な変更には具体的には、新しいデータ型やエンティティ型の導入、あるいはデータ出力への追加情報の包含といったものが含まれます。下記の拡張性を参照してください。
• 重大でない変更:行儀のよいクライアントにいかなる影響もないと期待されるAPIまたはデータ形式への変更。重大でない変更には、リテラル外の空白やJSONオブジェクトにおけるフィールドの順序への変更が含まれます。
• 安定したインターフェース: 破壊的変更および重大な変更が下記の方針によって告知されるAPIまたはデータ形式。どのインターフェースが安定と見なされるのかは、この文書で後に安定したインターフェースで定義します。

通知の方針

この節では、いつどこでクライアントの運用者および消費者が「安定したインターフェース」への変更を通知されるのかを定義します。不安定なインターフェースを考慮した保証はされません。

• 安定したインターフェースへの破壊的変更は、関連するメーリングリスト（wikidata-tech、 wikidataおよびpywikibot）とProject Chatで事前に適切に告知されます。告知は一般的には4週間前ですが、少なくとも変更がhttps://www.wikidata.org/に展開される2週間前にはなされます。変更は少なくとも展開の2週間前にはhttps://test.wikidata.org/でテストすることができるようになります。このような告知には題名の行にBREAKINGという語があります。
• 安定したインターフェースへの重大な変更は、関連するメーリングリスト（wikidata-tech、wikidataおよびpywikibot）とProject Chatで告知されます。告知は一般的には事前に少なくとも2週間ですが、少なくとも変更がhttps://www.wikidata.org/へ展開された1週間後にはなされます。変更は典型的には少なくとも展開の2週間前にはhttps://test.wikidata.org/でテストすることができるようになります。
• 安定したインターフェースへの重大でない変更は、一般的には告知されません。
• 不安定なインターフェースへの変更は、たとえ破壊的変更であっても告知されないかもしれません。
• この方針への重大な変更は、関連するメーリングリスト（wikidata-tech と wikidata）およびProject Chatで変更がなされる週のうちに告知されます。

拡張性

この節では、データモデルとデータ形式を拡張する方法を説明します。消費者はデータで出くわすかもしれない未知の構造を受け入れるために、この情報を考慮すべきです。

The Wikibase Data Model is designed to be extensible. In particular, it is possible to introduce new data types and new entity types. Well-behaved clients and consumers should thus be prepared to encounter unknown data types and entity types, and handle them gracefully, in a way appropriate for the use at hand. In many cases, it is appropriate to simply ignore such structures of unknown type.

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.

安定したデータ形式

この節では、我々が安定と見なしているデータ形式を列挙します。これらのデータ形式は、上記の通知の方針に従います。

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.

安定した公共の API

この節では、我々が安定と見なしているインターフェースを列挙します。これらのインターフェースは、上記の通知の方針に従います。

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.

不安定なインターフェース

この節では、我々が現状は安定と見なしておらず、したがって通知することなく互換性のない変更をするかもしれない、いくつかのインターフェースを列挙します。

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.

展望

この節では、将来に向けて計画あるいは検討されている改善に関する情報を提供します。

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.

履歴

この節では過去および計画されている破壊的変更を最新のものを上にして一覧にします。この方針が導入される以前の過去の一覧は不完全かもしれません。各変更は告知日および展開（デプロイメント）日と共に列挙されるべきであり、理想的には告知やあらゆる関連するチケットへのリンクを伴うべきです。

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