From 4d196e898d9212c2266d1e9848d1f5fb98a4d56b Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Wed, 22 Mar 2017 13:56:28 -0700 Subject: [PATCH] Add cref describing the situation with HTML forms The specification is currently in a slightly awkward state of both drawing analogies with HTML forms and supporting a different, more explicit paradigm with "hrefSchema". Add a note acknowledging the confusion and providing some context for the current state of things. --- jsonschema-hyperschema.xml | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/jsonschema-hyperschema.xml b/jsonschema-hyperschema.xml index 128da879..31e156a5 100644 --- a/jsonschema-hyperschema.xml +++ b/jsonschema-hyperschema.xml @@ -846,6 +846,23 @@ GET /foo/
+ + + While this section curently draws explicit analogies to HTML forms, + we expect significant changes to this analogy in future drafts. + In particular, "hrefSchema" removes the need for "schema" to + do double duty of either describing URL query parameters or + request body structure, but not both. HTML forms are designed to + abstract the encoding and submission mechanisms away from the + human end user. JSON Hyper-Schema allows for more flexibility, + and assumes that client libraries or programs can choose the + level of abstraction that is suitable for their audiences. + The current transitional state of this specification is intended + to allow experimentation and feedback on the more explicit + approach, while still offeriing some level of compatibility + with the previous two drafts. + + The following properties also apply to Link Description Objects, and provide functionality analogous to HTML forms, by providing a means for making a request with client- or user-selected information.