Remove "method" and analogies to HTML forms. #292
Conversation
jsonschema-hyperschema.xml
Outdated
| @@ -390,8 +389,13 @@ | |||
|
|
|||
| <section title="Links and data"> | |||
| <t> | |||
| "Form"-like functionality can be defined by use of the <xref target="method">"method"</xref> and <xref target="submissionSchema">"submissionSchema"</xref> keywords, which supplies a schema describing the data to supply to the server. | |||
| Functionality equivalent to dynamic URI generation is available through the <xref target="href">"href"</xref> template and <xref target="hrefSchema">"hrefSchema"</xref>. | |||
| "Form"-like functionality can be defined by use of the | |||
There was a problem hiding this comment.
I don't think we can use the term "Form-like" anymore. I think we can say this without using the word "form".
There was a problem hiding this comment.
Agreed. I think I looked at that, said to myself "I'll figure out what to say there later before I commit" and then didn't :-P I'll rework it.
There was a problem hiding this comment.
@jdesrosiers I realize now that I didn't fix this because the whole section gets totally rewritten in #293. So unless you think #293 is going to get substantially held up, I'm going to leave this as-is in this PR rather than figure out better wording that will get deleted immediately. I can always put up a small PR to address just this if #293 gets stuck anyway.
jsonschema-hyperschema.xml
Outdated
| "Form"-like functionality can be defined by use of the | ||
| <xref target="submissionSchema">"submissionSchema"</xref> and | ||
| <xref target="submissionEncType">"submissionEncType"</xref> keywords, | ||
| which supply a description of data to sent to the target resource for processing. |
There was a problem hiding this comment.
typo: "to sent to" => "to send to"
jsonschema-hyperschema.xml
Outdated
| The above example simulates the behavior found in earlier drafts using only "hrefSchema", | ||
| which would allow the concurrent use of "submissionSchema" on a "post" link. | ||
| The above example simulates the behavior handled in earlier drafts | ||
| with a "method" of "get" by using the new "hrefSchema" keyword, |
| <t> | ||
| The following properties also apply to Link Description Objects, and provide functionality analogous to <xref target="W3C.CR-html5-20140731">HTML forms</xref>, by providing a means for making a request with client- or user-selected information. |
There was a problem hiding this comment.
Mixed feelings about removing references to the biggest hypermedia format, but eh. Maybe it's for the greater good.
There was a problem hiding this comment.
@awwright Understandable, but yeah, I think it will provoke very useful feedback/discussions, and with #288 and #294 we're definitely not closing the discussion. Getting some distance from the way we've been referencing HTML will help us figure out what the right way (if any) really is. I think it's just been kind of on autopilot for a lot of people (not @jdesrosiers who has obviously put a lot of thought into it, but a lot of people who are not really questioning how the spec works as much).
The feedback to draft-wright-json-schema-hyperschema-00 and from the final review for draft-wright-json-schema-hyperschema-01 has made it clear that "method" is extremely confusing, and no two people can agree on the correct usage. The only clear impulse is to use the draft-luff-json-hyper-schema-00 meaning (explicit specification of HTTP methods), which is not the desired approach. "method" is not actually necessary now that "hrefSchema" and "submissionSchema" have separated the roles that were previously both implemented by "schema" depending on the value of "method". Therefore remove it to prevent incorrect assumptions about its behavior and gather feedback on what behavior is truly needed. With "method" gone, it makes sense to remove the references to HTML forms as the analogy is no longer direct. However, there are still open issues around both whether and how to explicitly indicate HTML form vs anchor semantics, and whether and how to allow directly specifying HTTP methods (as was allowed by draft-luff-json-hyper-schema-00). Since there are no longer citations of HTML, that reference has been removed. If a new keyword is added for HTML form semantics, then it will be restored as needed.
|
@jdesrosiers @awwright the latest commit should fix everything (I ended up replacing '"Form"-like' with 'Data input' because why not- I have to rebase the next commit either way). |
NOTE: Review this with whitespace changes turned off!!!
https://github.com/json-schema-org/json-schema-spec/pull/292/files?w=1
This has been split out from #290. It should not be merged without also
resolving the other parts of that larger change somehow, which will
likely restore some reference to HTML forms.
The feedback to draft-wright-json-schema-hyperschema-00 and from
the final review for draft-wright-json-schema-hyperschema-01
has made it clear that "method" is extremely confusing, and no
two people can agree on the correct usage. The only clear
impulse is to use the draft-luff-json-hyper-schema-00 meaning
(explicit specification of HTTP methods), which is not the
desired approach.
"method" is not actually necessary now that "hrefSchema" and
"submissionSchema" have separated the roles that were previously
both implemented by "schema" depending on the value of "method".
Therefore remove it to prevent incorrect assumptions about its
behavior and gather feedback on what behavior is truly needed.
With "method" gone, it makes sense to remove the references to
HTML forms as the analogy is no longer direct. However, there are
still open issues around both whether and how to explicitly
indicate HTML form vs anchor semantics, and whether and how to
allow directly specifying HTTP methods (as was allowed by
draft-luff-json-hyper-schema-00).
Since there are no longer citations of HTML, that reference has
been removed. If a new keyword is added for HTML form semantics,
then it will be restored as needed.