HAPI JSON schema needs updating for 3.2

[jvandegriff]

This needs to be done coincident with 3.2 release, since schema reference will be included in all responses.

(changelogs are key for hunting down impacts - PRs now keep track better)

[jvandegriff]

need to move schemas from verifier repo to main spec repo

[rweigel]

Schemas have been moved: https://github.com/hapi-server/data-specification-schema

[rweigel]

Before we can start on 3.2, we need to finish 3.0 updates.

A HAPI version update requires

1. (Bob) A new TestData server that implements the new features (remaining server-nodejs tasks for 3.0)
2. (Jon) Figuring out what changes were made to the specification (changelog helps, but often things are missed)
3. (Jon and Jeremy) Edits to the schema (Remaining task for 3.0: need to have stricter check for JSON references. For example, "fill": {"$ref": "#/definitions/fill"} is allowed, but current 3.0 schema only checks for object. It should check that if object, then key must be $ref, etc.)
4. (Bob) Additional code in the verifier for things not captured by the schema (for example, does the server have an endpoint of /about and does the server accept time.min and start) remaining verifier-nodejs tasks for 3.0
5. (Bob) Clients to be updated (For 3.0, plotting clients should handle time varying bins. For now, we can put in a warning when detected and update later.)

[jvandegriff]

Notes from an earlier discussion about how to indicate the presence or location of JSON schema for a JSON document:

There is no standard way for JSON to announce that it is following a schema.
Also, JSON Does not have namespaces.

json-schema-org/json-schema-spec#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",

[jvandegriff]

We are going to set a two week deadline to make progress on this, and then go with whatever we have after that for the 3.2 release. Since the last schema work was for version 2.0, the main effort will involve getting a 3.0 schema captured, then 3.1 and 3.2 are just tweaks.

[jvandegriff]

For now, the schema is a combined file for all the different JSON responses. Eventually, we need to split those into separate schemas for each response, but we are pushing that to later - the focus for now is to capture the correct schema in any form (i.e., leave it combined for now).

[jbfaden]

Jon and I split those out in the branch https://github.com/hapi-server/data-specification-schema/tree/jon-jeremy-mess-3.0 . This will be merged in once 3.2 is done.

Bob brought up keeping things in one file again, to avoid repeated code. JSON allows external references and this would be my preference.

[jbfaden]

There are a bunch of things we discovered which were never recorded here. For example, when a "$schema" property is found, Visual Studio Code will provide completions and pop-up documentation.

[jbfaden]

Here hovering over a timetag shows the documentation found in the schema: