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:
https://github.com/Wikidata/Wikidata-Toolkit/issues/237
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.
--
Daniel Kinzler
Senior Software Developer
Wikimedia Deutschland
Gesellschaft zur Förderung Freien Wissens e.V.