Wikidata talk:Stable Interface Policy

Recent breaking changes

When applying this policy backwards, what would have been the 2 or 3 most recent "breaking changes"?
--- Jura 16:03, 16 August 2016 (UTC)

Good question! I'll go through the mailing list archives and compile a list. I'll post it in the "History" section of the policy page, as Legoktm suggested. I'm starting with this query: https://www.mail-archive.com/search?q=breaking&l=wikidata-tech%40lists.wikimedia.org -- Daniel Kinzler (WMDE) (talk) 16:57, 17 August 2016 (UTC)

I'm not sure if it's worth doing the entire history, but 2 or 3 samples might be good.
--- Jura 05:05, 18 August 2016 (UTC)

status of RDF mapping

The RDF mapping of the Wikibase Data Model is supposed to be a stable data model, but the referenced page https://www.mediawiki.org/wiki/Wikibase/Indexing/RDF_Dump_Format says "Caution: This is work in progress. Until this warning is removed, any detail on this page can be changed without notice.." One or the other needs to be changed, preferably with notice. Peter F. Patel-Schneider (talk) 16:09, 16 August 2016 (UTC)

You are right, this is no longer correct. The Ontology is still in beta and may change without us bumping the version number, but we will still announce breaking changes according to the proposed policy. I will update the page banner. -- Daniel Kinzler (WMDE) (talk) 16:59, 17 August 2016 (UTC)

I also filed a ticket for making sure the docs are up to date: https://phabricator.wikimedia.org/T143229 -- Daniel Kinzler (WMDE) (talk) 17:17, 17 August 2016 (UTC)

JSON issues

The page uses JSON as an example of a specification that consumers can comply to. However JSON has quite a number of problems as a specification. If this page is going to continue to use JSON as an example, it should be more specific as to what sort of JSON consumers can expect.

There are two major issues with JSON as a specification for data interchange. One issue has to do with numbers - JSON allows arbitrary precision decimal numbers but many JSON consumers can only accept numbers that fit into IEEE floating point. Another issue is repeated names in objects - JSON allows an unordered set of name/value pairs but many consumers use name/value maps for objects. The recent IETF description of JSON at https://tools.ietf.org/html/rfc7159 has some good advice on these problems. Peter F. Patel-Schneider (talk) 16:45, 16 August 2016 (UTC)

Thank you for the useful pointer. We are indeed aware of these problems and are trying to work around them (the Quantity data type uses an arbitrary precision decimal represented as a string). This probably deserves more coverage in the spec for our JSON binding. Care to comment there? -- Daniel Kinzler (WMDE) (talk) 17:07, 17 August 2016 (UTC)

The page is apparently a mirror of something else. Is it still reasonable to make a comment on the talk page? Peter F. Patel-Schneider (talk) 00:44, 18 August 2016 (UTC)

You are right, the documentation is maintained as part of the source code. The talk page is still ok for comments, but a phab ticket would perhaps be better. For now, I have submitted an update of the JSON docs on gerrit: https://gerrit.wikimedia.org/r/#/c/305507/ -- Daniel Kinzler (WMDE) (talk) 14:44, 18 August 2016 (UTC)

The changes you have made in the ticket appear to cover the main bases. Peter F. Patel-Schneider (talk) 15:51, 18 August 2016 (UTC)

what is breaking?

"For instance, a well-behaved client will not break when encountering a new data type."

Certainly a client should not just dump core if it encounters a new data type.

However, the component of the client that reads the data could throw a catchable exception if it sees a new data type. I don't see that as breaking. Peter F. Patel-Schneider (talk) 16:46, 16 August 2016 (UTC)

Throwing an exception does not constitute "breaking" of and by itself. Letting the exception bubble up unhandled would be breaking. Throwing an undocumented/unchecked/unexpected exception could cause that. -- Daniel Kinzler (WMDE) (talk) 17:11, 17 August 2016 (UTC)

It is not always possible to produce output if new fields are encountered. Consider a consumer of the JSON dump whose API guarantee is that it outputs all property value information from the dump in an XML data form. This consumer cannot ignore new data types because that would violate its API guarantee. Peter F. Patel-Schneider (talk) 16:57, 16 August 2016 (UTC)

That just means that a well-behaved client simply cannot make such a guarantee. You can still make such a library, but it would not be considered well-behaved in the context of this policy, and we would not cater to it. -- Daniel Kinzler (WMDE) (talk) 17:11, 17 August 2016 (UTC)

OK, but if the guarantee was "either complete information or a known signal that something went wrong" would that be acceptable? Peter F. Patel-Schneider (talk) 00:55, 18 August 2016 (UTC)

Yes. In the end, what constitutes "breaking" depends on the expectations of your users. So basically, it "breaks" when the user thinks it does. Which may depend on something as trivial as the wording of an error message. -- Daniel Kinzler (WMDE) (talk) 14:47, 18 August 2016 (UTC)

versioning

This seems like an ideal time to add versioning to data formats. Why then is this opportunity being wasted? Peter F. Patel-Schneider (talk) 16:46, 16 August 2016 (UTC)

How is introducing a policy a good time to change a data format? I think introducing this policy is actually a reason to wait with changing the format, until the policy is established. -- Daniel Kinzler (WMDE) (talk) 17:13, 17 August 2016 (UTC)

Because this policy puts in place the underpinnings of semantic versioning. Minor versions will be bumped on significant changes. Major versions will be bumped on breaking changes. The versioning will provide machine-readable information that goes along with notification. Announcements can refer to the new version number. Consumers and clients can inspect the version number to see whether a change has happened. Peter F. Patel-Schneider (talk) 01:01, 18 August 2016 (UTC)

My department at work just had a meeting and I was talking about using Wikidata. I mentioned that the dump format was unversioned. This failed the "burst of laughter" test - members of the department were flabbergasted at the lack of versioning. "Interfaces 101" was mentioned. I realize that this is just an anecdote, but I think that it would be a typical reaction. What can be done to help add version information to the dumps? Peter F. Patel-Schneider (talk) 15:31, 23 August 2016 (UTC)

The main problem is that there is really no good place for the version info. The top level structure of the JSON dumps is a list. We would have to wrap the entire dump in a container structure to create something that is semantically sensible. If you have any ideas, please comment on phab:T92961. -- Duesentrieb (talk) 22:38, 23 August 2016 (UTC)

So the JSON dump is not JSON? JSON only has object, array, value, and string - no lists. I would have expected this to be prominently mentioned on the JSON dump page! (Yes, yes, JSON is regularly abused this way.) I'll comment on the page you mention. Peter F. Patel-Schneider (talk) 23:45, 23 August 2016 (UTC)

It's JSON. Just look at the dump. Array and list are the same in my mind (except in Perl maybe). -- Daniel Kinzler (WMDE) (talk) 09:14, 24 August 2016 (UTC)

I hadn't looked at a JSON dump as I've been using the RDF dumps. I just downloaded one, and, yes, the dump is a JSON array of JSON objects. I should have looked at the dump instead of relying on descriptions of it. Peter F. Patel-Schneider (talk) 15:10, 24 August 2016 (UTC)

Array and list are quite different in many programming languages so it is generally a good idea to not describe one as the other. Peter F. Patel-Schneider (talk) 15:10, 24 August 2016 (UTC)

duplicate reference

I am on travel, so excuse my ip and my lack of understanding of the non-desktop interface.

One frustrating issue is when such a gadget as the one who duplicate references break. It is an extremely useful tool, and it now directly limit how much I can contribute here. /Innocent bystander on travel

The fact that our DOM and JavaScript interfaces are unstable is indeed sad, and often causes Gadgets to break. We hope to change this in the future. For now, all I can do is to record the reality that they aren't stable at this time. -- Daniel Kinzler (WMDE) (talk) 17:14, 17 August 2016 (UTC)

No guarantees are made

in Notification Policy - that sentence appears to be unfinished (or at least lacking a period).--Smalyshev (WMF) (talk) 23:27, 16 August 2016 (UTC)

fixed, thank you -- Daniel Kinzler (WMDE) (talk) 17:20, 17 August 2016 (UTC)

Significant changes no longer suitable for projects?

Wikimedia (and Wikidata) frequently rely on volunteers enhancing features during time limited projects. Personally, I think it's important that implementation of such features is accompanied by the people who designed them. This even a couple of days beyond the actual go-live date. I wonder if the two weeks stated here don't exclude this. Given that none of the consumers other than WMF pay for the Wikidata service, I wonder if a commitment of two weeks should be given. Obviously, there may be (or may have been) factors that already added weeks to such changes before.
--- Jura 07:28, 17 August 2016 (UTC)

Sorry, I don't understand what you are getting at. Can you rephrase? -- Daniel Kinzler (WMDE) (talk) 17:21, 17 August 2016 (UTC)

If someone works on a "significant change" for 1 month, they would have to start testing after 10 days (allowing two weeks of testing/advance announcement of the change). After the release (10+14), the would have a couple of days left to follow-up on "go live".
--- Jura 05:03, 18 August 2016 (UTC)

...and that would be problematic e.g. for a GSoC project. Yes.

In the past, it has usually worked this way: The volunteer would complete the implementation (including code review) within the official period. We would then announce, follow up, and deploy later. Volunteers are not expected to stay around for that, though of course, it's always good to have the original author of the code around, if they have time. -- Daniel Kinzler (WMDE) (talk) 14:51, 18 August 2016 (UTC)

I think it would also be interesting for them to actually see it fly. If the purpose of this policy is allow consumers to spell out some evergreening provision, maybe it's sufficient to label initial production releases with "alpha" status and just declare them "real" some time later.
--- Jura 15:42, 18 August 2016 (UTC)

Of course it's great to see it fly, but if what they did is a breaking change, they'll have to be patient. Typically though, such projects introduce new functionality, which can be deployed without or with brief notice. Or they can be deployed as an optional Gadget or Beta-Feature, or on test.wikidata.org.

Declaring significant changes to stable interfaces as "alpha" does not help - if the change is there, clients have to handle it. Calling it "alpha" actually makes it worse: clients can't rely on it staying as it is, it may change yet again. -- Duesentrieb (talk) 10:01, 19 August 2016 (UTC)

Maintain a list of breaking changes

Mostly from a wiki-historian point of view, it would be nice if there was a listing of breaking changes (could just be links to mailing list posts) maintained somewhere on the wiki (maybe a subpage of this page) for historical record, instead of needing to trawl through mailing list archives. Legoktm (talk) 08:29, 17 August 2016 (UTC)

This is a very good idea! I'll go and add a "History" section, and fill in a few breaking changes from the past. -- Daniel Kinzler (WMDE) (talk) 17:22, 17 August 2016 (UTC)

I believe there was a recent change in the wikidata API allowing only https access (turning off http). Would that be considered a breaking change and on the list? ArthurPSmith (talk) 16:10, 23 August 2016 (UTC)

That was a braking change to all of the web API on Wikimedia sites. It was widely announced as such, but perhaps not on the channels specific to Wikidata. You got a point there - I'm not sure how we can best ensure that breaking changes to the overall Wikimedia infrastructure are announced to the Wikidata channels specifically. For now, I suppose you will also have to monitor wikitech-l or mediawiki-api lists. -- Duesentrieb (talk) 22:43, 23 August 2016 (UTC)

Examples

It would be useful to have examples of the terminological categories. An example of a significant well-behaved consumer, particularly a consumer that has clients or consumers of its own, would be very useful. Peter F. Patel-Schneider (talk) 12:56, 17 August 2016 (UTC)

That would be nice to have, but I don't have the capacity to sort through code and find out which consumers are well-behaved. If you know of some examples, please put them here on the talk page! -- Daniel Kinzler (WMDE) (talk) 17:23, 17 August 2016 (UTC)

The problem is that I don't know of any well-behaved consumers. My concern is that the definition of well-behaved is so tight that there will be very few of them. If the developer team can't come up with any examples either, then why bother catering for them? Peter F. Patel-Schneider (talk) 01:08, 18 August 2016 (UTC)

It's no extra effort catering to well-behaved clients. Having to cater to non-well-behaved clients would be extra effort.

The definition of well-behaved exists as a guideline for developers. "If you follow these rules, your stuff isn't going to suddenly break". That's the idea.

I would hope that at least pywikibot is well-behaved in the sense defined by the policy. I have not verified this, and I'm not going to. I would hope that the authors of pywikibot will at least aspire to be well-behaved in the given sense. -- Daniel Kinzler (WMDE) (talk) 14:54, 18 August 2016 (UTC)

Wikidata or Wikibase?

Is this specific to Wikidata or does it apply to Wikibase in general? --Nemo 15:14, 23 August 2016 (UTC)

It applies to Wikidata (services and data provided). The policy is here to tell people when and where they can expect a warning before a change "goes live". A policy like this for Wikibase wouldn't make sense - when would we announce changes? Before merging them into the master branch?

What would make sense for Wikibase would be stable releases with proper release notes which list all the breaking and other changes. But we currently don't have any release process for Wikibase. -- Daniel Kinzler (WMDE) (talk) 18:13, 23 August 2016 (UTC)

Clarify stability of homogeneous lists

The policy is currently not clear about the treatment and interpretation of homogeneous lists/sets. The policy currently says: Data structures my be added in any syntactically appropriate place. So if there is a list associated with a "links" property, containing some sort of Link object, it would accordingly be OK to add a Coconut to it. That's of course not desirable.

A list (set, collection, array, container, etc) that is by spec or convention understood to be homogeneous must stay homogeneous. Adding an incompatible element to it constitutes a breaking change, since it changes the interpretation of the container (it's no longer a homogeneous container). The policy should state this clearly. -- Duesentrieb (talk) 19:51, 24 August 2016 (UTC)

I don't see much, if any, difference between adding a new kind of thing to an array (e.g., the top-level array in a dump) versus adding a new kind of thing to an object (e.g., an object corresponding to an entity). Both add new unexpected information. Both can be handled by ignoring this information. It is somewhat harder to determine whether an array value is unexpected than determining whether an object name/value pair is unexpected, but I see this as a matter of degree, not a matter of kind. Peter F. Patel-Schneider (talk) 20:59, 24 August 2016 (UTC)

If you think of it in terms of an object oriented language with generics, adding a field to an interface is not a breaking change, but changing the element type of a collection is. It boils down to the Liskov substitution principle. When adding a field, all assumptions about pre-existing fields still hold. If you add an incompatible element, you break the assumption of homogenity. -- Duesentrieb (talk) 21:53, 28 August 2016 (UTC)

Adding a field to an object can be a breaking change. The new field can change the meaning of the entire object. Consider, for example, adding a new boolean field to the entity structure signalling that the entity as a whole is deprecated. Even with entities being read-only adding this new field would be a breaking change. And anyway the policy allows for type-breaking changes via adding new datatypes. Given both of these, I still don't see much, if any, difference between adding a new kind of thing to an array versus adding a new kind of thing to an object. Peter F. Patel-Schneider (talk) 04:37, 29 August 2016 (UTC)

Well, by that logic, any change is a breaking change. If that is an interpretation that is useful in your context, feel free to interpret all changes as breaking. -- Duesentrieb (talk) 15:04, 31 August 2016 (UTC)

Not every change is a breaking change, but there is no wholely syntactic way of determining that a change is non-breaking, as adding a deprecated field shows. Given this, the only ways of distinguishing breaking changes from non-breaking changes are to provide some out-of-band information about the meaning of a change or to have some information in the data structure that distinguishes breaking changes from non-breaking changes, or, ideally, both. Peter F. Patel-Schneider (talk) 20:11, 5 September 2016 (UTC)

Proposed change to to the "Extensibility" section

Prompted by Peter F. Patel-Schneider's comments about the stability of homogeneous lists, I propose to change the wording of the Extensibility section of the policy as folows:

---

Similarly, bindings such as the JSON representation of the Wikibase data model are designed to be extensible. Data structures my be added in any syntactically appropriate place (such as additional fields on JSON objects, or additional elements or attributes in an XML document). To allow well-behaved clients to safely ignore such additional structures, such additions will be treated as breaking changes if they have any impact on the interpretation of other, preexisting data structures. Conversely, they will be treated as non-breaking if they have no impact on the interpretation of any preexisting parts of the data. 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 homogenous, 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 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 heterogenous and essentially acts like a map. However, if the parent element is defined or implied to be a homogenous 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.

[Edit 2016-09-13] 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 changing the element type of a collection as described above.

[Edit 2016-09-13] Also, in the Breaking change bullet point of the Terminology section, the example should be updated to use "format" instead of structure:

• Breaking change: a change to an API or data format that is likely to cause problems in clients or other consumers. Breaking changes include removal of API functions, parameters, or data fields and changes to the interpretation or format of data fields.

---

Comments welcome below. Thanks! -- Daniel Kinzler (WMDE) (talk) 12:18, 5 September 2016 (UTC)

Why single out homogeneous lists and sets? It seems to me that all loosening of typing should be treated the same. Peter F. Patel-Schneider (talk) 20:16, 5 September 2016 (UTC)

Sure, it should. The problem is defining what "loss of typing" means in a structured of untyped lists and maps (resp arrays and objects). Changing or removing fields is an obvious case, changing guarantees about the element type of a collection is another. Adding a field isn't (that's why subclassing works as polymorphism, and that's what LSP should guarantee). What else do you want to cover? How would you define it in this context? -- Daniel Kinzler (WMDE) (talk) 10:29, 7 September 2016 (UTC)

Loosening the advertised typing of a field should count as a breaking change. For example, if a field value is advertised as being an integer loosening it to any JSON number would be a breaking change. Similarly, if a field value type is advertised as being one of a given number of alternatives, adding a new alternative would be a breaking change. Peter F. Patel-Schneider (talk) 11:01, 7 September 2016 (UTC)

Of course, but that's not something I would put under Extensibility, which is about non-breaking changes. I believe your example is covered by "Breaking changes include removal of API functions, parameters, or data fields and changes in the interpretation or structure of data fields.". Perhaps "interpretation or structure" could be changed to "interpretation, structure, or format", to make this abundantly clear. -- Daniel Kinzler (WMDE) (talk) 16:58, 7 September 2016 (UTC)

Perhaps, but adding a new datatype or even a new kind of entity appears to be advertised as non-breaking changes. I don't see why these loosenings of typing are non-breaking while loosening of homogeneous lists is breaking. Peter F. Patel-Schneider (talk) 17:47, 13 September 2016 (UTC)

I have added some clarifications to my proposed change. I plan to apply and announce this change tomorrow. -- Daniel Kinzler (WMDE) (talk) 13:02, 13 September 2016 (UTC)

• Is this purely interface/data-structure or also content related?
  --- Jura 13:12, 13 September 2016 (UTC)

• I would interpret "Breaking changes include removal of API functions, parameters, or data fields and changes to the interpretation or format of data fields" [emphasis added] to mean it is content related. For example, the documentation used to say times were a particular instant in time, with a time zone, meaning they could be normalized to UT. But since the software has never worked for time zones, and the minimum precision is 1 day, in reality the vast majority of times are local times in the locality of the event. If the documentation were revised to reflect this reality, all data consumers should be put on notice to check how they are importing times, and import them as local times with an unknown time zones, rather than UT times. Jc3s5h (talk) 14:58, 13 September 2016 (UTC)

• • What Jc3s5h says is correct, though that is not my understanding of "content" in this context. To me, "content" is what wiki users can define and edit, and that is not covered by this policy. The policy is about interfaces, including data structures and the format of primitives we use to represent our content, it is not about the structures that users can build, like e.g. a subclass hierarchy build with P279. -- Daniel Kinzler (WMDE) (talk) 15:05, 13 September 2016 (UTC)

Database Schema as a stable API

I plan to add the wikibase (SQL) database schema as a stable interface. Typically, a database schema is considered internal, but since we have tools on labs that may rely on the current schema, breaking changes to the schema should be announced as such. To address this, I plan to add the following paragraph to the Stable Public APIs section:

The database schema as exposed on Wikimedia Labs is considered a stable interface. Changes to the available tables and fields are subject to the above notification policy.

In addition, I plan to add the following paragraph to the Extensibility section:

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 unique indexes are not breaking changes.

-- Daniel Kinzler (WMDE) (talk) 15:57, 28 October 2016 (UTC)

I agree with that in principle, people heavily really on these tables (and the indices) these days. But we should still note that the database scheme is more influx than other stable interfaces (we don't really want to encourage people to use these over for example the API, because they are more influx than the API modules).

That either means we should put them in a separate section or at least adding a note, saying that we try to handle them like stable interfaces, but they still are going to (continuously) change. Cheers, Hoo man (talk) 19:45, 28 October 2016 (UTC)

Good point! Even though in practice, changes to the DB schema are harder to depoly than changes to the API. How about this phrasing:

We acknowledge that third party tools on Wikimedia Labs and Tool Labs 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.

Do you think that would be more appropriate? -- Daniel Kinzler (WMDE) (talk) 17:09, 30 October 2016 (UTC)

Yes, that sounds appropriate for me. The database structure has been designed (and is being updated solely) to serve the needs we have on "main" storage right now, that needs to be clear (and your sentence is doing that well). Cheers, Hoo man (talk) 23:18, 30 October 2016 (UTC)

“Stable interfaces” section

The “Definitions” section contains a dead link:

Which interfaces are considered stable is defined in the Stable Interfaces later in this document.

The document doesn’t have a “Stable Interfaces” section – it has “Stable Data Formats” and “Stable Public APIs”. Should the sentence be rephrased to link to both of those sections, or should they be made subsections of a new “Stable Interfaces” section? --Lucas Werkmeister (WMDE) (talk) 16:32, 14 June 2017 (UTC)

Apparently this has been slightly changed in the meantime (permalink) – the link now points to #stable-interfaces (rather than #Stable_Interfaces), and there is an element with that ID on the page: an {{Anchor|stable-interfaces}} at the very end of the “Stable Data Formats” section. (This was done by Kaganer in Special:Diff/513920977.) Lucas Werkmeister (WMDE) (talk) 11:34, 16 January 2024 (UTC)

Some property descriptions should be subject to the stable interface policy

A discussion at Property talk:P625#Perimeter of this property, the talk page for the "coordinate location" property, illustrates that it isn't enough for the behavior and Mediawiki documentation for a datatype to be stable. Many users will not read the documentation, but instead will read the Wikidata label and description of a property that is strongly associated with the datatype. For datatypes and properties that are strongly associated, the Mediawiki documentation and Wikidata label and description should have the same meaning.

If the association is not quite so strong, the Wikidata label and description should be a subset of the Mediawiki datatype, but the Wikidata label and description should generally not be a superset of the Mediawiki datatype. The only exception I can envision would be if the Mediawiki datatype is in the process of being expanded or replaced by a more general dataytype. Jc3s5h (talk) 15:18, 3 March 2019 (UTC)