Description
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.