Add request/response implementation requirements #449
Conversation
|
@vasilakisfil here is another PR on top of the rewrite that is probably relevant to your interests, although may make more sense once I submit the companion PR updating the HTTP section to match this. |
jsonschema-hyperschema.xml
Outdated
| </t> | ||
| <t> | ||
| Requests that take a target representation as a payload SHOULD use the | ||
| "targetSchema" and "targetMediaTYpe" keywords for input description and |
There was a problem hiding this comment.
Small typo here on "targetMediaTYpe"
|
Thanks! This is very helpful section actually that clearly explains the uses of |
|
Based on the positive feedback so far, and given that this does not change implementation requirements, I'm going to go ahead and merge this so it can be part of the "final review" announcement. This does not in any way lock in these changes, and feedback and suggestions for a better approach are still very much wanted and appreciated. |
This mostly involves explaining that hyper-schema is not a system for executing requests and processing response. It informs a user agent how to construct various requests, and is used to interpret whatever response (expected, error, whatever) is returned.
dlax
left a comment
dlax
left a comment
There was a problem hiding this comment.
While certainly useful, this addition is a bit verbose I think. So just mentioning which paragraphs could be removed to gain a bit of conciseness.
| <t> | ||
| RPC systems that pipe many application operations with arbitrarily different | ||
| request structures through a single hypermedia protocol operation are outside | ||
| of the scope of a hypermedia format such as JSON Hyper-Schema. |
There was a problem hiding this comment.
I find this paragraph is more confusing than helpful.
| <t> | ||
| User agents are expected to understand protocol status codes and response | ||
| media types well enough to handle common situations, and provide enough | ||
| information to client applications to handle domain-specific responses. |
There was a problem hiding this comment.
This paragraph also seems superfluous.
gregsdennis
added
clarification
4 participants
This mostly involves explaining that hyper-schema is not a system
for executing requests and processing response. It informs a
user agent how to construct various requests, and is used to
interpret whatever response (expected, error, whatever) is returned.
Also define "operation" up front as I keep forgetting where it's defined
and not being sure whether it was defined recently enough in the spec
for a reader to have noticed and remembered.
This is groundwork for better advice on HTTP, and is intended to provide
context around how hyper-schema systems should work with requests
and responses that is non-HTTP-specific. The HTTP section will then
apply HTTP methods, headers, etc. to this conceptual framework
to illustrate how HTTP should be used with hyper-schema LDOs.