peterbrightwell
commented
4 years ago I've made a start (on validate branch... at the moment this is just so I don't lose my experiments) but will need to come back to it at a later time.
validate.sh will look for examples in each RAML file and find their corresponding schemas. Some are included directly, others via a type definition (and unfortunately each spec seems to have done that differently).
None of the validation tools I've tried will correctly handle $refs to local schemas. I propose to use the python jsonschema, and temporarily patch the references with file: prefixes, and any pathname change required.
See also https://github.com/AMWA-TV/nmos-lint-scripts/pull/5
Follow-up to https://github.com/AMWA-TV/nmos-template/issues/3 and https://github.com/AMWA-TV/nmos-doc-build-scripts/issues/1. Text below is from the latter:
In addition to the basic JSON linting performed as part of the CI, it would great to:
This would have prevented several mistakes previously made during schema design and spec version ups. Seems like there are several reasonable looking JSON Schema engines that could be used during CI.
Tricky bit is identifying which schema should be used to validate which example file, because our JSON formats do not contain embedded metadata to indicate that (and indeed that's recommended practice - instead, out-of-band mechanisms like
Linkresponse headers or IANA media-type parameters are usually needed).We could rely on the RAML
typeindication but we'd have to make sure all files in examples/ were referenced from the RAML (or at least only validate the ones that were). Unused examples may be a mistake anyway...The other obvious approach would rely on a .schemas.json file in each repo that simply mapped instances in examples/ to schemas in APIs/schemas, and error if the filenames didn't match up.