search

ThreeSixtyGiving / standard

The 360Giving data standard for UK philanthropic giving
http://www.threesixtygiving.org
Other
10 stars 15 forks source link

Providing example values in the Schema #228

Open BobHarper1 opened 6 years ago

BobHarper1 commented 6 years ago

JSON Schema draft 6* introduced the "examples" meta keyword

This keyword can be used to provide sample JSON values associated with a particular schema, for the purpose of illustrating usage. It is RECOMMENDED that these values be valid against the associated schema.

Considering our work around templates and improved publisher guidance, example values might provide a reliable way of maintaining and providing valid example data.

*The standard currently uses draft-04, I believe that it is also valid as draft-06

stevieflow commented 6 years ago

The standard currently uses draft-04, I believe that it is also valid as draft-06

@Bjwebb @kindly would you be able to check this?

Bjwebb commented 6 years ago

Checking http://json-schema.org/draft-06/json-schema-release-notes.html#q-what-are-the-changes-between-draft-04-and-draft-06 this seems to be true. We don't use any of the stuff that has backwards compatible changes. I've also checked validation against the json schema schema.

I've also checked draft-07, and the standard is valid against that also, because draft-06->draft07 is fully backwards compatible.

Note that actually validating draft-06 and draft-07 is currently a problem for the tools we use. See also Tim's comment on https://github.com/OpenDataServices/fireproofbox-standard/pull/2#issuecomment-394661730. Although, this shouldn't be such a problem for examples, as they'll be ignored by the validator anyway.