Change Details

We should make clear to 3rd party users of our data and APIs what stability guarantees we give (and don't give). The idea is to make explicit the implications of the [[https://en.wikipedia.org/wiki/Robustness_principle|robustness principle]] in the context of Wikibase. In particular: * JSON and XML may contain additional fields, attributes, or elements in any location. Additional fields do not influence the interpretation of pre-existing fields, and can thus be safely ignored. * Entity types, data types, and value types may be added. Clients should handle unknown kinds of elements or values gracefully (typically be skipping them, or passing them through unchanged). * The MediaWiki web API modules are considered a stable interface. This also applies to the serialization formats supported for output. * "stable" currently does not mean "versioned". It currently only means that due notice will be given of breaking changes. For interface versioning, see {T92961} * Other stable interfaces are the output of Special:EntityData and the format used in JSON and RDF dumps. * The contents of MediaWiki XML dumps is //not// a stable interface. Some key parts of such a policy document are outlined in an email to wikitech-l from February 5 2016: [[https://www.mail-archive.com/wikidata-tech@lists.wikimedia.org/msg00902.html|On interface stability and forward compatibility]]. The policy needs to be findable on mediawiki.org, and should be prominently linked from [[https://www.mediawiki.org/wiki/Wikibase/DataModel/JSON|Wikibase/DataModel/JSON]] and similar pages.

We should make clear to 3rd party users of our data and APIs what stability guarantees we give (and don't give). The idea is to make explicit the implications of the [[https://en.wikipedia.org/wiki/Robustness_principle|robustness principle]] in the context of Wikibase. In particular: * JSON and XML may contain additional fields, attributes, or elements in any location. Additional fields do not influence the interpretation of pre-existing fields, and can thus be safely ignored. * Entity types, data types, and value types may be added. Clients should handle unknown kinds of elements or values gracefully (typically be skipping them, or passing them through unchanged). We should also make clear which interfaces are considered stable: * The MediaWiki web API modules are considered a stable interface. This also applies to the serialization formats supported for output. * "stable" currently does not mean "versioned". It currently only means that due notice will be given of breaking changes. For interface versioning, see {T92961} * Other stable interfaces are the output of Special:EntityData and the format used in JSON and RDF dumps. * The contents of MediaWiki XML dumps is //not// a stable interface. Finally, we should adopt a policy for due notice of significant changes: * distinguish between "breaking" and "significant". Changing the way we serialize time values would be "breaking", adding a new data type would not be "breaking", but still "significant". * establish channels and notice periods for significant and breaking changes. Some key parts of such a policy document are outlined in an email to wikitech-l from February 5 2016: [[https://www.mail-archive.com/wikidata-tech@lists.wikimedia.org/msg00902.html|On interface stability and forward compatibility]]. The policy needs to be findable on mediawiki.org, and should be prominently linked from [[https://www.mediawiki.org/wiki/Wikibase/DataModel/JSON|Wikibase/DataModel/JSON]] and similar pages.

We should make clear to 3rd party users of our data and APIs what stability guarantees we give (and don't give). The idea is to make explicit the implications of the [[https://en.wikipedia.org/wiki/Robustness_principle|robustness principle]] in the context of Wikibase. In particular: * JSON and XML may contain additional fields, attributes, or elements in any location. Additional fields do not influence the interpretation of pre-existing fields, and can thus be safely ignored. * Entity types, data types, and value types may be added. Clients should handle unknown kinds of elements or values gracefully (typically be skipping them, or passing them through unchanged). We should also make clear which interfaces are considered stable: * The MediaWiki web API modules are considered a stable interface. This also applies to the serialization formats supported for output. * "stable" currently does not mean "versioned". It currently only means that due notice will be given of breaking changes. For interface versioning, see {T92961} * Other stable interfaces are the output of Special:EntityData and the format used in JSON and RDF dumps. * The contents of MediaWiki XML dumps is //not// a stable interface. Finally, we should adopt a policy for due notice of significant changes: * distinguish between "breaking" and "significant". Changing the way we serialize time values would be "breaking", adding a new data type would not be "breaking", but still "significant". * establish channels and notice periods for significant and breaking changes. Some key parts of such a policy document are outlined in an email to wikitech-l from February 5 2016: [[https://www.mail-archive.com/wikidata-tech@lists.wikimedia.org/msg00902.html|On interface stability and forward compatibility]]. The policy needs to be findable on mediawiki.org, and should be prominently linked from [[https://www.mediawiki.org/wiki/Wikibase/DataModel/JSON|Wikibase/DataModel/JSON]] and similar pages.