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.

[dlax]

@handrews So if I understand correctly, the "client application" is aware of hypermedia controls but would not care (but could) about their implementation (in terms of media type and protocol) whereas a "user agent" would be responsible for operating the links on behalf of the "client application" under media types and protocol constraints.

Note that the intro section would be new, so it would come in as a separate commit or PR from the commit/PR rewriting the existing text.

I guess I'd prefer a single PR for the whole rewrite so that progress can be followed and we can have a global vision. No problem with the introduction coming as a single commit. Granted this is a lot of work, thanks for talking this!

[handrews]

[EDIT: The tone of this was supposed to be bemused rather than angry, but I totally failed at that]

@dlax this proves that I will never, ever understand how other people want PRs organized. I anticipated either you or at least one other person demanding that this be split out.

Someone always wants things either split or merged. I have no idea what I'm going to do with this. Write it however works for me and post it, I guess. It's guaranteed that someone will complain no matter what I do, so I'll just do whatever seems easiest for me.

[dlax]

Henry Andrews a écrit :

@dlax <https://github.com/dlax> this proves that I will never, ever understand how other people want PRs organized. I anticipated either you or at least one other person demanding that this be split out.

Not sure what you mean here? I don't think I "demanded" anything. I just acknowledged your "warning" and basically said "this is fine by me".

…

Someone always wants things either split or merged. I have no idea what I'm going to do with this. Write it however works for me and post it, I guess. It's guaranteed that someone will complain no matter what I do, so I'll just do whatever seems easiest for me.

[handrews]

Oh, goodness, I apologize, that's not what I meant at all. I should have let that sit for a while before posting. You were absolutely not demanding anything and I did not think so even when I was writing that.

[handrews]

I just meant that I figured that if I included it, someone would ask that it be split out, so I was trying to get out ahead of it. And then it turns out that you're fine with that. I wasn't even angry when I wrote that, not that it comes across correctly :-(

More bemused that I can never seem to guess how to organize my work.

[handrews]

Draft of rewrite posted as PR #427.

[handrews]

Merged #427