Hi folks,
I’m about to disappear on parental leave at the end of the week but I thought I’d leave you all with something.
I wrote a very basic proof of concept HSDS API validator. It’s definitely not suitable for production use cases and isn’t strictly re-usable as I didn’t separate the library and CLI functions, but based on some testing I’ve done with sample data it seems to be reliable enough to put out into the world as something people might want to try out or use as an example to do their own implementations.
This started when I had a little niggle in my brain about what I would need to validate any HSDS data that came my way and then thought about what a bare-bones validator would actually look like.
I then sat down at the computer and ended up coming up with this.
It’s a CLI with only one command at the moment: validate, this takes an API stub and then tests that it returns what is expected from the / endpoint. This response should also include the URL to the openapi definition file, so it then takes that and iterates through all the paths and does some basic validation:
- is the URL accessible (status code)
- is the data empty? (I became aware that if we did basic schema-based validation on the result of
GET /servicesthen an empty response is technically valid!) - is the data well-formed HSDS? (this uses whichever schema is defined by the openapi.json file as the expected schema of the result)
It produces a JSON report which can then be saved to file or piped elsewhere to do what you want with. The report has a key for each endpoint, with the report underneath.
For endpoints which need IDs, you can supply a JSON file containing arrays of ids to test for each endpoint.
Also; it works on profiles!! In my testing I tested vanilla HSDS and Open Referral UK HSDS. This is thanks to the Profiles tooling automatically generating well-formed openapi.json files during profile setup which point towards profile-specific schemas. Therefore as long as the result for GET / contains the appropriate URL to the profile’s openapi.json file then the hard work has been done.
The major limitation is that it does not create thorough reports for the schema validation; and only reports on the first error it encounters. This is due to the JSON Schema validation library in python being a bit puritanical. It is possible to get a full list of validation errors but it was beyond the scope of the playing around I wanted to do here. If you’re interested, then Open Data Service’s CoVE wrangles this for you.
I am not planning on developing this any further as I have achieved my goal of getting a proof of concept validator working. Open Data Services let me work on this during work hours (basically last Friday afternoon and this morning), but don’t worry we haven’t billed Greg for any of this time!
Anyway, I hope this is useful for some folks.