Realise that this thread is getting a little stale, but I’ve finally been able to sit down and finish my replies to it.
Headline: I am in full agreement that we should add $id properties to the HSDS Schemas. Where I’m hesitant, is that I don’t (yet) understand the implications for Profile Maintainers due to how the HSDS Schema Tools generate Profile schemas via JSON Merge Patches. However, new/existing Profiles can still explicitly add their own $id properties in the interim. I plan to do some experiments when I have time, and report back with a recommendation for the way forward.
The validation engine, which I envision (I could be way off base), would potentially only require 2 URL values…the data feed and a schema version that it must satisfy.
I know we’ve had discussions to this effect over technical meetings, calls, and the odd email exchange but I think I’ll write it down here so people scouring the forum can find it!
With the way that HSDS’ API Spec and Schemas are currently defined, validators should only really need a single URL to do validation. The API Spec defines that GET / should return an object which contains the following:
{
"version": "3.2",
"profile": "https://url-to-your-profile-here",
"openapi_url": "https://url-to-openapi-url-here"
}
From here, you can just retrieve the openapi.json file used to describe the API. This will then define the endpoints etc. and importantly it defines the response schemas by way of URL to the compiled HSDS Schemas.
That means for every path defined in the openapi.json file, a validator can then automatically know what the response should look like by retrieving the schema associated with it. This is the fundamental “wiring up” of the API spec and the data models defined by the schemas.
But what about Profiles? Well, the HSDS Schema tools command used to generate a Profile requires a URL used to define your profile. When it’s generating that Profile’s openapi.json file; it will then use that URL as a basis to generate the url for your Profile’s versions of the schemas. The only manual wiring you’ll need to do is when you’re defining your own endpoints, I think.
As long as the Profile’s schemas are available at the URLs defined in the openapi.json file (if you supply a github or gitlab repo url as the profile url, this should happen automatically); all a validator needs is a “root URL”, and then from there it can retrieve, in a step-wise manner, all of the declarative information it needs to evaluate the results of an API call against the Schemas.
Where I think we still need $id properties in the schema; is that these canonical URLs for schemas are sort of implicit now, whereas declaring them in the $id of the schemas themselves allows tools such as validators to cache them nicely.
