Hyper-schema vocabulary support

[karenetheridge]

as per slack

Hyper-Schema is a non-validation vocabulary. A Hyper-Schema implementation would be a generic hypermedia client similar to Ketting (https://github.com/badgateway/ketting). It's not dissimilar to an SDK that you can generate from an OpenAPI document, but it's way better because one implementation supports all APIs. It's like a web browser. A browser doesn't generate code for each website you visit. All the information the browser needs is in every request. Hyper-Schema adds hypermedia to plain JSON allowing you to interact with it in much the same way as you would with a web browser.

Although Hyper-Schema has more to do with annotations than validation, validation does play a role in Hyper-Schema. If you are on a listing page and you follow a link to create and append a new instance, a JSON Schema will be used to validate that the request you are about to make is valid.

If you want to support Hyper-Schema in a validator, all you need to support is the describedby link relation. If a schema has a describedby link, it means that the schema you get by following the link should also be valid against the instance. It's kinda like a dynamic allOf.

{
  "type": "object",
  "properties": {
    "toggle": { "type": "string" }
  },
  "links": [
    { "rel": "describedby", "href": "/schema/{toggle}" }
  ]
}

Here's a demo API showing basics of using Hyper-Schema, https://github.com/jdesrosiers/todo-api. It uses draft-04 for two reasons. First, and most important, draft-04 is the only draft to have a complete and correct implementation. It was created by the author of the draft-04 spec, so it shows how Hyper-Schema was intended to be used. The second reason is that since draft-04, Hyper-Schema changed in fundamental ways that I don't like, so I still prefer draft-04 (despite its warts) to anything that has come since.

You can read more about what I don't like about the changes since draft-04 in the README. I also present a couple ideas about improvements.

Use the generic Jsonary web client (http://json-browser.s3-website-us-west-1.amazonaws.com/?url=http%3A//hypermedia-todo.herokuapp.com/) to click through the API and visualize how Hyper-Schema enhances JSON with hypermedia.

Look through the schemas (https://github.com/jdesrosiers/todo-api/tree/master/schema) to see how easy it is to apply Hyper-Schema (in draft-04 at least (it gets more complicated in later drafts)) to existing JSON Schemas.

[karenetheridge]

Remember to bundle these files:

  'draft2020-12/hyper-schema.json'        => 'https://json-schema.org/draft/2020-12/hyper-schema',
  'draft2020-12/links.json'               => 'https://json-schema.org/draft/2020-12/links',
  'draft2020-12/meta/hyper-schema.json'   => 'https://json-schema.org/draft/2020-12/meta/hyper-schema',
  'draft2020-12/output/hyper-schema.json' => 'https://json-schema.org/draft/2020-12/output/hyper-schema',
  'draft2019-09/hyper-schema.json'        => 'https://json-schema.org/draft/2019-09/hyper-schema',
  'draft2019-09/links.json'               => 'https://json-schema.org/draft/2019-09/links',
  'draft2019-09/meta/hyper-schema.json'   => 'https://json-schema.org/draft/2019-09/meta/hyper-schema',
  'draft2019-09/output/hyper-schema.json' => 'https://json-schema.org/draft/2019-09/output/hyper-schema',

[karenetheridge]

Stalled pending revival of the hyperschema project.