Explain "targetSchema" and HTTP PATCH. #277
Conversation
This keeps coming up, and I believe that this clarifies the existing behavior (vs, say, using "schema" to describe PATCH input).
|
After more discussions and looking at more ways people have used "targetSchema" in the past, I have added more clarification. At least I think it is clarification- again if @awwright disagrees then this should not go in to the forthcoming draft. My goal is to clarify the existing intent, not change it. "targetSchema" is often misinterpreted as a response schema, when |
"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.
|
@Relequestual @jdesrosiers how do you feel about this one? I can wait until #280 (replacement for #276) is resolved before merging this, as they are somewhat related. |
| 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 |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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).
There was a problem hiding this comment.
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.
This keeps coming up, and I believe that this clarifies the existing
behavior (vs, say, using "schema" to describe PATCH input).
As with the previous pull request, this is appropriate for
draft-wright-json-schema-hyperschema-01 (Draft 06) if and only if
it is agreed to be a clarification rather than a change.