What is a JSON Hyper-Schema? #366
Conversation
Despite having a whole section describing how hyper-schema builds on validation, it was never referenced or listed as a normative specifciation. Also, we had labled the meta-schema link as a validation schema in an apparent copy-paste error. Finally, improve wording around building on the other specs in the same way as was done for the validation spec referincing core.
This reworks the general descriptive text to emphasize how Hyper-Schema fits in to the RFC 5988 link model, or more accurately the RFC 5988bis revision currently in development. By presenting the Web Linking model as the central foundation for Hyper-Schema, and emphasizing the relationship between Hyper-Schema and the link context, the focus should be a bit more clearly on hypermedia rather than api request/responses. Also defined "operation" which I apparently just started using in that section without explaining it at all.
| defined in <xref target="I-D.nottingham-rfc5988bis"/>. These terms respectively | ||
| correspond with "Context IRI" and "Target IRI" as used in | ||
| <xref target="RFC5988">RFC 5988</xref>. | ||
| Although defined as IRIs, in common scenarios they are also URIs. |
There was a problem hiding this comment.
It seems that RFC5988bis has been approved as a "Proposed Standard" (https://datatracker.ietf.org/doc/draft-nottingham-rfc5988bis/writeup/). So should we keep references to the old RFC?
There was a problem hiding this comment.
When it actually gets assigned a new RFC number, we will. For now, the xref system needs a document it understands, and that's the I-D. That's a "send after approval" form letter, not an actual indication of approval quite yet.
| A Link Description Object (LDO) is used to describe a single link relation from the | ||
| instance to another resource. | ||
| A Link Description Object (LDO) is a serialization of the abstract model specified | ||
| in Section 2 of <xref target="I-D.nottingham-rfc5988bis"/>, defines a link as |
There was a problem hiding this comment.
I'm not sure the comma after the <xref .../> is appropriate. As is, I interpret the "defines" verb with "Link Description Object" as subject, is it intended? Or should it in Section 2 of <xref target="I-D.nottingham-rfc5988bis"/> which defines a link as [...]?
There was a problem hiding this comment.
Yeah, I meant to have a "which" between the xref/comma and "defines a link", will fix, thanks!
| resource. The value MUST be a registered link relation from the | ||
| <xref target="RFC5988">IANA Link Relation Type Registry established in RFC 5988</xref>, | ||
| or a normalized URI following the <xref target="RFC3986">URI production of RFC 3986</xref>. | ||
| </t> | ||
|
|
||
| <t> | ||
| The relation to the target is interpreted as from the instance that the schema | ||
| The link context is interpreted as from the instance that the schema |
There was a problem hiding this comment.
I'm not sure the "from" is still needed. I'd read it better as The link context is interpreted as the instance that the schema (or sub-schema) applies to, [...].
There was a problem hiding this comment.
I'm not worried about this level of wording right now. Let's just get a yes/no on the direction. I don't plan to merge this without a significant reworking for grammar, consistency, wording, etc. I just want conceptual feedback right now.
|
@dlax yeah I was happy to get rid of "server-supplied". There's still some client vs user agent language that may need cleaning up. I'll either get it when I do the formal version of this casual draft PR, or will do it as a separate fix if it's too confusing otherwise. |
|
Seems broadly fine. |
|
Thanks folks- I'll leave this up for a few more days in to give a few more people a chance to see it. I'll probably submit PRs for simpler wording adjustments and file issues for anything more broadly philosophical. |
NOTE: This is the "trial balloon" PR I just said I would post in issue #226. This means that I do not expect this PR to be accepted as is. I was poking at some other stuff and ended up reworking some descriptions almost by accident. The language is inconsistent and I was not overly careful about making sure I hit every relevant reference. Some language is lifted verbatim from @dret's linkset draft, which I can fix before committing.
I am just looking for a yes/no/wtf gut reaction at this point. If everyone is a "yes", I can tidy up the language based on feedback and resubmit.
Also note: the commit from #365 is here because it's near-trivial, I can't be bothered to rebase it out of a trial balloon, and it reads better with it anyway. Take your pick.
This reworks the general descriptive text to emphasize how
Hyper-Schema fits in to the RFC 5988 link model, or more
accurately the RFC 5988bis revision currently in development.
By presenting the Web Linking model as the central foundation
for Hyper-Schema, and emphasizing the relationship between
Hyper-Schema and the link context, the focus should be a bit
more clearly on hypermedia rather than api request/responses.
Hopefully this will help us define and communicate Hyper-Schema's scope.
Also defined "operation" which I apparently just started using
in that section without explaining it at all.
For reference, it is helpful to take a look at Section 2 of RFC 5988biss may be seen here: https://mnot.github.io/I-D/rfc5988bis
Also paging @dlax, @jdesrosiers, @awwright, @geemus, @seagreen