Skip to content

Explain "targetSchema" and HTTP PATCH. #277

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Mar 23, 2017
Merged

Explain "targetSchema" and HTTP PATCH. #277

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
023ff76
Explain "targetSchema" and HTTP PATCH.
handrews Mar 20, 2017
ff50f1b
Clarify "targetSchema" and HTTP
handrews Mar 21, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 21 additions & 2 deletions jsonschema-hyperschema.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@
<!ENTITY rfc3986 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3986.xml">
<!--<!ENTITY rfc4287 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4287.xml">-->
<!--<!ENTITY rfc5226 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5226.xml">-->
<!ENTITY rfc5789 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5789.xml">
<!ENTITY rfc5988 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5988.xml">
<!ENTITY rfc6570 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6570.xml">
<!ENTITY rfc7231 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7231.xml">
Expand Down Expand Up @@ -703,9 +704,26 @@ GET /foo/

<section title="targetSchema">
<t>
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'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.
</t>

<section title="&quot;targetSchema&quot; and HTTP">
<t>
The relationship between a resource's representation and
HTTP requests and responses is determined by
<xref target="RFC7231">RFC 7231, section 4.3.1 - "GET", section 4.3.4 "PUT", and section 3.1.4.2, "Content-Location"</xref>.
In particular, "targetSchema" suggests what a client can expect
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If I'm reading this correctly, proper HTTP semantics when combined with targetSchema suggest that you should be able to read and write (PUT) the same fields? I mean the target shcema properties can use readOnly, but we didn't always have that, right?

Just making I'm infurring the correct implications from the wording.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, that's correct, except that "readOnly" has been part of Hyper-Schema since the beginning (when it was folded in with core and validation in one draft).

But yes, in HTTP performing a GET and then PUT-ing the result of the GET directly back should be a successful no-op (aside from things like auto-updated timestamps).

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We did adjust the definition of "readOnly" to clarify that it means "under the control of the server" and not "you are forbidden from including this field in PUTs" (the latter would force violation of HTTP semantics so that would be bad).

The server can decide whether it needs to detect changes to such fields and raise errors (400 or 409), or whether to silently ignore things. For instance a field that is present to reflect state changes elsewhere probably should never raise an error because of the following scenario:

  • GET on /foo/1, field "x" has value "y"
  • some request on /bar/9 causes /foo/1's "x" to change value to "z"
  • PUT the representation back to /foo/1 modifying the value of field "w"

On that last put, "x" will still have value "y" but on the server, its value is now "z". So that could look like a change. But as a "readOnly" field, the server is allowed to ignore that apparent change.

A resource can also offer different levels of enforcement using the "Prefer" header value's "handling=strict" or "handling=lenient" options.

The above x/y/z/w example probably shouldn't cause an error either way, but for a field that is not likely to change out from under you during a GET/modify/PUT, in lenient mode you could silently ignore changes, while returning a 409 or 400 in strict mode.

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 <xref target="RFC5789">RFC 5789</xref>, the request structure
for an HTTP PATCH is determined by the combination of "targetSchema"
and the request media type.
</t>
</section>
<section title="Security Considerations for &quot;targetSchema&quot;">
<t>
This property has similar security concerns to that of "mediaType".
Expand Down Expand Up @@ -950,6 +968,7 @@ GET /foo/
<references title="Informative References">
&rfc2046;
<!--&rfc5226;-->
&rfc5789;
&rfc5988;
&rfc7231;
&html5;
Expand Down