HAPI responses should include the JSON schema reference

jvandegriff commented 2 years ago

And the schemas should be put online with DOIs.

jvandegriff commented 1 year ago

How to reference the schema is not too hard: probably add a link to it in the status block, for example.

Question: is there a standard way for JSON to advertise the presence of a schema?

Question: are there multiple JSON schema syntax options? Ans: they seem to have converged and we use: json-schema.org

This will take some research and time.

Need to then add schema refs to all the examples.

Should 3.2 require a schema to be present? Maybe wait for 4.0 to require it?

jvandegriff commented 1 year ago

There is no standard way for JSON to announce that it is following a schema. Also, JSON Does not have namespaces. See this issue from the JSON schema people:

https://github.com/json-schema-org/json-schema-spec/issues/828

So how we manage this is probably up to us.

From https://cdaweb.gsfc.nasa.gov/hapi/capabilities

{
  "$schema": "https://hapi-server.org/schemas/3.2/schema",
  -OR- one schema for each end point
  "$schema": "https://hapi-server.org/schemas/3.2/capabiliites/schema",

  "HAPI": "2.0",
  "status": {"code": 1200, "message": "OK"},
  "outputFormats": ["csv","json","binary"]
}

Probably one line is enough.

Maybe consider putting the web link in the schema key:

  "$https://json-schema.org/schema": "https://hapi-server.org/schemas/3.2/schema",
  -OR- one schema for each end point
  "$https://json-schema.org/schema": "https://hapi-server.org/schemas/3.2/capabiliites/schema",

rweigel commented 1 year ago

Conclusion:

Add refs to the applicable schema in HAPI schema definition files as $schema
Require something like (ideally) $schema: "https://hapi-server.org/schemas/HAPI-3.2.json#capabilites" in all responses. It may be that we would have to split up a single file `$schema: "https://hapi-server.org/schemas/3.2/capabilites", which will take some effort.

Wait on item 2. till version 4.0.

Do item 1. asap.

rweigel commented 6 months ago

Item 1. is tracked in https://github.com/hapi-server/data-specification/issues/188

hapi-server / data-specification

HAPI responses should include the JSON schema reference #134