Hi Markus!
I would like to elaborate a little on what Lydia said.
Am 04.08.2016 um 09:27 schrieb Markus Kroetzsch:
It seems that some changes have been made to the JSON serialization recently:
This specific change has been announced in our JSON spec for as long as the document exists. https://www.mediawiki.org/wiki/Wikibase/DataModel/JSON#wikibase-entityid sais:
WARNING: wikibase-entityid may in the future change to be represented as a single string literal, or may even be dropped in favor of using the string value type to reference entities.
NOTE: There is currently no reliable mechanism for clients to generate a prefixed ID or a URL from the information in the data value.
That was the problem: With the current format, all clients needed a hard coded mapping of entity types to prefixes, in order to construct ID strings from the JSON serialization of ID values. That means no entity types can be added without breaking clients. This has now been fixed.
Of course, it would have been good to announce this in advance. However, it is not a breaking change, and we do not plan to treat additions as breaking changes.
Adding something to a public interface is not a breaking change. Adding a method to an API isn't, adding an element to XML isn't, and adding a key to JSON isn't - unless there is a spec that explicitly states otherwise.
These are "mix and match" formats, in which anything that isn't forbidden is allowed. It's the responsibility of the client to accommodate such changes. This is simple best practice - a HTTP client shouldn't choke on header fields it doesn't know, etc. See https://en.wikipedia.org/wiki/Robustness_principle.
If you use a library that is touchy about extra data per default, configure it to be more accommodating, see for instance https://stackoverflow.com/questions/14343477/how-do-you-globally-set-jackson-to-ignore-unknown-properties-within-spring.
Could somebody from the dev team please comment on this? Is this going to be in the dumps as well or just in the API?
Yes, we use the same basic serialization for the API and the dumps. For the future, note that some parts (such as sitelink URLs) are optional, and we plan to add more optional bits (such as normalized quantities) soonish.
Are further changes coming up?
Yes. The next one in the pipeline is Quantities without upperBound and lowerBound, see https://phabricator.wikimedia.org/T115270. That IS a breaking change, and the implementation is thus blocked on announcing it, see https://gerrit.wikimedia.org/r/#/c/302248/.
Furthermore, we will probably remove the entity-type and numeric-id fields from the serialization of EntityIdValues eventually. But there is no concrete plan for that at the moment.
When we remove the old fields for ItemId and PropertyId, that IS a breaking change, and will be announced as such.
Are we ever going to get email notifications of API changes implemented by the team rather than having to fix the damage after they happened?
We aspire to communicate early, and we are sorry we did not announce this change ahead of time.
However, this is not a breaking change by the common understanding of the term, and will not be treated as such. We have argued about that on this list before, see https://www.mail-archive.com/wikidata-tech@lists.wikimedia.org/msg00902.html. I have made it clear back then what we consider a breaking change and what not, and I have advised you that being accommodating in what your client code accepts will avoid headaches in the future.
To make this even more clear, we will enact and document something similar to my email from February as official policy soon. Watch for an announcement on this list.