JSON-stat 2.0 (simplified)

[Xavier Badosa]

JSON-stat has been around for more than 10 years (the first release is from 2011). The latest version (2.0) was published in 2015, more than 6 years ago.

The specs haven't changed since then. Because changes between the different versions were small and version 2.0 was new, the documentation covered all versions highlighting the new features of v. 2.0. Besides, the documentation was built upon the documentation of previous versions, where some elements were open and discussions and suggestions were included to help closing them.

https://json-stat.org/format/

After 6 years, leaving references to prior releases or suggestions about open elements seems confusing. I'm not planning to remove the current documentation but, unless someone thinks this is not a good idea, I will create a simplified JSON-stat 2.0 documentation.

For the sake of simplicity, would it be a good idea to remove (in this simplified version) references to elements that have had zero success so far (and could end up being deprecated in future releases), like "child" or "coordinates"? Maybe also "note"? Or would that be too confusing?

One of the worst JSON-stat features is error handling. This has always been an open issue. The documentation of version 2.0 just reproduced what was already in version 1.0 as a suggestion. It's a pity 2.0 didn't face this issue with a closed proposal that was aligned with the new 2.0 features. It seems to me now that the correct way to deal with errors in JSON-stat 2.0+ is supporting "error", not as a property, but as a value of the "class" property. Because error handling is still an open issue, in this simplified documentation I could include the suggestion of supporting "error" as a "class" value.

Any feedback is welcome,

Xavier

[Xavier Badosa]

Privately someone replied to me that "error handling (application logic) should not be part of JSON-stat (data dissemination) and be dealt by the application in other, separate ways". 

If that is so, in the simplified documentation maybe no mention to errors should be included.

On the other hand, standard http errors are very general and many data providers seem to feel that more info should be returned to developers (like for example that a particular value of a parameter is not valid). That was the goal of including error detailed information in responses with the associated general http standard code. What do you think?

Another simplifying improvement of the documentation could probably be to document dataset and collection responses separately.

X.

[Xavier Badosa]

I ended up separating the full spec, now available at

https://json-stat.org/full/

from a new simplified documentation addressed to new JSON-stat users (producers or consumers):

https://json-stat.org/format/

This new simplified documentation (JSON-stat 2.0 Dataset Format -simplified-) focuses only on dataset responses, doesn't reference previous JSON-stat versions and doesn't include the less popular optional features of the format.

I hope it will help people not familiar with the format to understand the main features behind it,

X.