Description
Section 6.6 Link Input starts with this sentence:
There are four ways to use client input with a link, and each is addressed by a separate link description object keyword.
The keywords referred to are presumably:
- hrefSchema
- headerSchema
- targetSchema
- submissionSchema
I think the sentence is misleading: while hrefSchema is about client input, the other schemas are about interaction with the link, but not about user input.
My suggestion goes beyond editing the sentence, it is a reconsideration of the current structure. A key principle is - and doubtless should be - alignment with the generic link model from RFC 8288. There we have the link property "target attributes", reflected here by section 6.5 Link Target Attributes. It includes 6.5.3. targetMediaType and 6.5.4 targetSchema. All very well.
The issue is that
- 6.6.2 header Schema
- 6.6.4.1. submissionMediatype
- 6.6.4.2. submissionSchema
should also be part of 6.5 Link Target Attributes, as they clearly give information about the target, more precisely, how to interact with it. The contents of
- 6.6.3 Manipulating the Target Resource Representation
finally, might be merged into 6.5.3 and 6.5.4.
How uneasy the current structure is, becomes obvious when trying to relate the sentence quoted in the beginning of this posting ("four ways to use client input ...") to the subsections following it: you would expect four matching subsections, but the third is more like a reference into contents found in 6.5.