On 08/05/2016 08:57 AM, Daniel Kinzler wrote: > Am 05.08.2016 um 17:34 schrieb Peter F. Patel-Schneider: >> So some additions are breaking changes then. What is a system that consumes >> this information supposed to do? If the system doesn't monitor announcements >> then it has to assume that any new field can be a breaking change and thus >> should not accept data that has any new fields. > > The only way to avoid breakage is to monitor announcements. The format is not > final, so changes can happen (not just additions, but also removals), and then > things will break if they are unaware. We tend to be careful and conservative, > and announce any breaking changes in advance, but do not guarantee full > backwards compatibility forever. > > The only alternative is a fully versioned interface, which we don't currently > have for JSON, though it has been proposed, see > <https://phabricator.wikimedia.org/T92961>. > >> I assume that you are referring to the common practice of adding extra fields >> in HTTP and email transport and header structures under the assumption that >> these extra fields will just be passed on to downstream systems and then >> silently ignored when content is displayed. > > Indeed. > >> I view these as special cases >> where there is at least an implicit contract that no additional field will >> change the meaning of the existing fields and data. > > In the name of the Robustness Principle, I would consider this the normal > case, > not the exception. > >> When such contracts are >> in place systems can indeed expect to see additional fields, and are >> permitted >> to ignore these extra fields. > > Does this count? > <https://mail-archive.com/[email protected]/msg00902.html>
This email message is not a contract about how the Wikidata JSON data format can change. It instead describes how consumers of that (and other) data are supposed to act. My view is that without guarantees of what sort of changes will be made to the Wikidata JSON data format, these are dangerous behaviours for its consumers. >> Because XML specifically states that the order of attributes is not >> significant. Therefore changes to the order of XML attributes is not >> changing >> the encoding. > > That's why I'm proposing to formalize the same kind of contract for us, see > <https://phabricator.wikimedia.org/T142084>. This contract guarantees that new fields will not change the interpretation of pre-existing ones, which is strong, but I don't see where it guarantees that the meaning of entire structures will not change, which is very weak. Consider the rank field. This doesn't change the interpretation of existing fields. However, it changes how the entire claim is to be considered. >> Here is where I disagree. As there is no contract that new fields in the >> Wikidata JSON dumps are not breaking, clients need to treat all new fields as >> potentially breaking and thus should not accept data with unknown fields. > > While you are correct that there is no formal contract yet, the topic had been > explicitly discussed before, in particular with Markus. > >> I say this for any data, except where there is a contract that such >> additional >> fields are not meaning-changing. > > Quote me on it: > > For wikibase serializations, additional fields are not meaning changing. > Changes > to the format or interpretation of fields will be announced as a breaking > change. > >>> Clients need to be prepared to encounter entity types and data types they >>> don't >>> know. But they should also allow additional fields in any JSON object. We >>> guarantee that extra fields do not impact the interpretation of fields they >>> know >>> about - unless we have announced and documented a breaking change. >> >> Is this the contract that is going to be put forward? At some time in the >> not >> too distant future I hope that my company will be using Wikidata information >> in its products. This contract is likely to problematic for development >> groups, who want some notion how long they have to prepare for changes that >> can silently break their products. > > This is indeed the gist of what I want to establish as a stability policy. > Please comment on <https://phabricator.wikimedia.org/T142084>. > > I'm not sure how this could be made less problematic. Even with a fully > versioned JSON interface, available data types etc are a matter of > configuration. All we can do is announce such changes, and advise consumers > that > they can safely ignore unknown things. > > You raise a valid point about due notice. What do you think would be a good > notice period? Two weeks? A month? Human-only due notice can only be a part of well-behaved software ecosystem. Software ends up being used in places separated from its initial developers, indeed from any developer. Requiring software to silently accept breaking additions means that breaking additions will usually break something even with a long notice period. There can also be no fixed notice period. Sometimes software can be changed and re-deployed in a day or a week. Often, however, change and re-deployment can take several months. Right now I would be leery of a two-week notice period, as it is entirely possible that this would fall within a vacation period for a group. Peter F. Patel-Schneider Nuance Communications _______________________________________________ Wikidata mailing list [email protected] https://lists.wikimedia.org/mailman/listinfo/wikidata
