What does it mean to implement Hyper-Schema?

[handrews]

I think that we should also have an introductory section explaining what an implementation of Hyper-Schema would look like, and what it is called. For JSON Schema validation, it's pretty clear that the thing one would implement is a validator. But people do implement other things (code/ui/doc generators) which is where many feature requests arise that do not fit into validation.

For Hyper-Schema, we use terms like "user agent" and "client", but it's pretty vague as to what those mean, exactly, and where Hyper-Schema fits in. While "user agent" does have a somewhat formal meaning, "client" could mean the user agent, or could mean a client application.

This is particularly important when considering HATEOAS, and discussing what the "application state" is and how it is maintained. Hyper-Schema should not become a treatise on HATEOAS, but a few pointers defining terminology and explaining how the concepts align would be very helpful.

The "user agent" here is a generic client. Like a web browser does for interactive hypermedia, the JSON Hyper-Schema driven user agent understands media types and protocols, but not the applications that use those media types and protocols.

The "client application" (unless someone has a better term) sits on top of the "user agent" and is aware of application-specific concepts. But it does not necessarily need to directly understand media types and protocols any more than a human using a browser does. It can, of course (as JavaScript applications running within the browser often do). But it should be possible to program an application on top of a Hyper-Schema aware user agent without worrying about how application/[*+]json, application/schema+json, HTTP, HTTPS, mailto: URIs, etc. etc. get used behind the scenes.

[handrews]

This should also help us figure out what a Hyper-Schema conformance test suite would look like.

[handrews]

Thoughts on implementation components and test cases (some of these are optional as they are MAY requirements, like recognizing collections via "item" links, or protocol-dependent, like HTTP's "allow"):

• Target URI resolution: given an instance which is valid against a schema containing a link, and (optionally) user input, produce the correct URI for the link, or the correct error (missing required template variable, input failed validation, input not allowed, etc.)
• Input pre-population from the instance: This is specific to URI input, somewhat included in URI resolution but should be tested separately as well since it is an intermediate step with a distinct outcome
• Input validation: Produce the correct validation output for each type of possible input (URI, request headers, target representation payload, submission payload), probably using true/false schemas to keep this orthogonal to testing validation itself
• Context identification: Produce the correct anchor URI, or if no URI can be constructed due to a lack of fragment syntax, the correct-except-for-fragment URI plus a JSON Pointer (or other description) of the point within the document that would otherwise be identified by a fragment
• Exposing values correctly: just verifying that if you ask for the title, description, or any other field that you get the correct value back (near-trivial, but important to not drop or hide these fields)
• Recognizing collections: traversing a "collection" link produces a collection, and an instance (or sub-instance) with an "item" link having that (sub)instance as its context is also a collection (raises issues of how deeply to look for "item" links- should that be a configurable limit? is that part of the spec?)
• Recognizing HTTP (and other protocol?) target hints, such as correctly answering whether a particular HTTP method is (non-authoritatively) supported, or what the (non-authoritative) acceptable patch media type is (need to decide how far to go on this- some hints are very common and will be expected to be broadly supported, others get very obscure)
• Serializing HTTP (and other protocol?) headers: we are sort-of piggybacking off of another I-D proposal for JSON representation of headers, but there is a good bit of leeway there. Do we define our own test suite for commonly used headers? (again, we would need to decide how far to go with this set of tests)

[handrews]

Another component that needs implementing and testing is determining whether a given link applies to a given (sub)instance. The interesting things to test are the ones in the "Integration with validation" section (or whatever I called it). Ensuring that while schemas deep in allOf and validating anyOf/oneOf/then/else branches contribute links, schemas in no-validating branches and under not do not.

[handrews]

Largely addressed in #427

[handrews]

Merged #427. Further work is needed in the test repository, but we'll track that separately.