From 023ff7636e7321806a96c89cae009d858e4eeddd Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Mon, 20 Mar 2017 11:16:12 -0700 Subject: [PATCH 1/2] Explain "targetSchema" and HTTP PATCH. This keeps coming up, and I believe that this clarifies the existing behavior (vs, say, using "schema" to describe PATCH input). --- jsonschema-hyperschema.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/jsonschema-hyperschema.xml b/jsonschema-hyperschema.xml index 128da879..ef2aa1b1 100644 --- a/jsonschema-hyperschema.xml +++ b/jsonschema-hyperschema.xml @@ -703,7 +703,7 @@ GET /foo/
- This property provides a schema that is expected to describe the link target, including what a client can expect if it makes an HTTP GET request, and what it should send if it replaces the resource in an HTTP PUT request. This property is advisory only. + This property provides a schema that is expected to describe the link target, including what a client can expect if it makes an HTTP GET request, and what it should send if it replaces the resource in an HTTP PUT request. The request structure for HTTP PATCH is described by the combination of this schema and the media type of the PATCH request payload. This property is advisory only.
From ff50f1b42b573764aaffee488a5b087a1247abed Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Mon, 20 Mar 2017 22:39:33 -0700 Subject: [PATCH 2/2] Clarify "targetSchema" and HTTP "targetSchema" is often misinterpreted as a response schema, when it in fact is the representation of the target resource which may or may not appear in various responses. The previous draft clarified this somewhat by referencing GET responses and PUT requests. This separates the HTTP information from the field's primary definition, and expands it to the other relevant HTTP cases. --- jsonschema-hyperschema.xml | 23 +++++++++++++++++++++-- 1 file changed, 21 insertions(+), 2 deletions(-) diff --git a/jsonschema-hyperschema.xml b/jsonschema-hyperschema.xml index ef2aa1b1..f5d65c23 100644 --- a/jsonschema-hyperschema.xml +++ b/jsonschema-hyperschema.xml @@ -6,6 +6,7 @@ + @@ -703,9 +704,26 @@ GET /foo/
- This property provides a schema that is expected to describe the link target, including what a client can expect if it makes an HTTP GET request, and what it should send if it replaces the resource in an HTTP PUT request. The request structure for HTTP PATCH is described by the combination of this schema and the media type of the PATCH request payload. This property is advisory only. + This property provides a schema that is expected to describe + the link target's representation. Depending on the protocol, + the schema may or may not describe the response to any particular + request sent to the link. This property is advisory only. - +
+ + The relationship between a resource's representation and + HTTP requests and responses is determined by + RFC 7231, section 4.3.1 - "GET", section 4.3.4 "PUT", and section 3.1.4.2, "Content-Location". + In particular, "targetSchema" suggests what a client can expect + for the response to an HTTP GET or any response for which + the "Content-Location" header is equal to the request URI, + and what a client should send if it replaces the resource + in an HTTP PUT request. + Per RFC 5789, the request structure + for an HTTP PATCH is determined by the combination of "targetSchema" + and the request media type. + +
This property has similar security concerns to that of "mediaType". @@ -950,6 +968,7 @@ GET /foo/ &rfc2046; + &rfc5789; &rfc5988; &rfc7231; &html5;