Emphasize context per RFC 5988bis

[handrews]

The reworking of text to define things around the instance (or sub-instance) as the link context instead of simple "server-supplied" data was well received in trial balloon change #366.

This issue is for discussing the idea and ensuring we have the concept and wording right, after which point I will file a new PR. If no one comments I'll just take a pass at it similar to the trial balloon but narrowly focusing on this one concept.

[handrews]

Here's a possible reworked organization of JSON Hyper-Schema, both to frame things in 5988bis terms and to introduce the various concepts at the right time. The sections involved should be either obvious from 5988bis or from the current draft. Client input description is not part of 5988bis (unless considered a kind of target attribute, I suppose). It seemed worth putting in its own subsection.

1. Introduction
2. Conventions and Terminology
3. Overview
4. Meta-schema
5. Schema keywords
   1. Interaction with validation
   2. base
   3. links
6. Link description objects
   1. Context
      1. anchor
      2. anchorPointer
   2. Relation type
      1. rel
      2. "self" links
      3. "collection" and "item" links
   3. Target
      1. href
      2. hrefPointers
   4. Target attributes
      1. title
      2. description
      3. targetSchema
      4. targetHints
      5. mediaType
   5. Client input description
      1. Links, operations, and data
      2. hrefSchema
      3. headerSchema
      4. submissionEncType
      5. submissionSchema

[handrews]

I think I would like to add a section 7 which would be one or more examples that we would use to illustrate how all of the pieces fit together. For instance, if the hrefRequired proposal from #49, or something like it, is added, then calculating the actual URI goes something like this:

1. Start by combining base and href to get the full URI template [EDIT: Actually, probably resolve both independently, with the keywords other than href applying identically to base if it has any template variables]
2. Extract the variable names, which default to reading from fields in the context instance
3. Apply hrefPointers to adjust the location within the instance corresponding to each variable
4. If hrefSchema is present:
   1. Optionally pre-populate the resolution data set with any instance data matching those variables
   2. Ask the client for input for any variables that do not have an hrefSchema value of false
   3. Add the client input to the resolution data set, overriding any pre-populated values
   4. Validate the resolution data set against hrefSchema (if it fails validation, error out here)
5. For any variables in the resolution data set that still lack values, populate them from the instance as adjusted by hrefPointers
6. If hrefRequired is present, verify that all variables listed there have values (if not, error out here)
7. Apply the RFC 6570 URI Template resolution algorithm using the full URI Template (base + href) and the computed resolution data set

While we do need isolated examples demonstrating each possible feature, it is very hard to understand the system without some overall examples that show the order in which to apply the keywords and line them up with various use cases to motivate the structure of the system as a whole.

[handrews]

Another good thing to show in the examples section is how to manage application state (via links) vs resource state (via representation). For example, instead of writing links with verb-ish extension relation types like "pay" and "cancel", write a link with the IANA-registered relation type "payment", and show how to represent the payment's state (unconfirmed, pending, canceled, completed) in the representation. And how both the client (by setting state to "pending" or "canceled", or maybe by issuing a DELETE to cancel instead of having an explicit canceled state?) and server (by setting state to "completed" on its own) can affect that state through multiple operations defined by a single link.

While we don't want to turn the spec into a how-to guide for APIs, this sort of thing is a very fundamental confusion for people approaching Hyper-Schema, and it would also illustrate the proper use of targetSchema (which very few people get right on the first try- I certainly did not).

Thanks to @philsturgeon for the very practical example topic.

[handrews]

I have moved the comment that was here to #413 as it is separate from the 5988bis reorganization.