We had an HSDS workgroup call on this topic.
There seemed to be general agreement on:
- Structuring the schema development into a folder of schemas as long at there is a way to compile the datapackage.json from them (which there is)
- We need to define APIs specification with JSON Schema and we can use these to help do that.
- Adding examples to the schema.
I think there is not complete agreement on:
Having JSON versions of the standard that contains nested data and therefore has an opinionated way to structure HSDS i.e to agree on a primary representations
So for this we have to assess the pros and cons of dong this.
Pros:
- Have an easier way to validate HSDS.
- Means that we can have good external validation tooling that works not just for particular APIs but for standard itself.
- Have better validation rules, especially ones that span relations, so the standard could say if an “organization has at least 1 service”.
- Less proliferation of different JSON structures used, to aid interoperability.
Cons:
- Less flexibility for publishers to use the HSDS “data model” in any way they choose.
- Data will have to be denormalized in some way i.e taxonomy terms repeated each time. This could cause issues for consumer if a publisher uses different data each time.
The sub question, is if we do agree to the above:
What representation(s) should be standardized/mandated?
I think it was agreed that the following should be standardized:
- Service
- Service at Location
- Organization with full service list (when there are never too many services for a particular org)
The question remains: what is acceptable for a publication to produce in order to be conformant?
This simple answer could be, any of them. However, ideally could mandate one for better interoperability. Obviously, we would also say that a datapackage would also be accepted.