feedback about section '"targetSchema" and HTTP'

[dlax]

The intent of section "targetSchema" and HTTP is not quite clear currently. In particular, the discussion about "Accept" header in the second paragraph seems out of place. Same for the part on submissionSchema at the end. At least, this needs clarification and rewording.

I just sent #468 to slightly improve the introduction, but that's not enough and I'm not sure what to do next without having a better idea of the original intent.

Probably related, there's also a paragraph in section Content negotiation and schema evolution about "Accept" header that I don't get the point of. Especially, "Accept" being a request header, I find it surprising that it could appear in hyper-schema links which (as far as I understand) either advertise responses or submission requests.

[handrews]

For "Accept", yes, it's a request header, and the headerSchema is for describing valid request header values. So I don't quite understand the surprise. Could you elaborate a bit more?

Also, could you please give more detail on your problem with submissionSchema? I don't understand what is unclear about it. In HTTP the "submission" fields are for POST requests. What is confusing about that?

[dlax]

For "Accept", yes, it's a request header, and the headerSchema is for describing valid request header values. So I don't quite understand the surprise. Could you elaborate a bit more?

I think it was a matter of wordings. In particular the paragraph:

The media type of the representation is given by the "targetMediaType" field. Alternatively, possible available media types MAY be advertised for HTTP-accessible resources using the "accept" field in "headerSchema", corresponding to the HTTP "Accept" header.

Admittedly, I never seriously thought about putting an Accept in headerSchema but maybe this is appropriate and there are use-cases for this. So fine.

The rework in #476 makes this clearer anyways, thanks!

[dlax]

Also, could you please give more detail on your problem with submissionSchema? I don't understand what is unclear about it. In HTTP the "submission" fields are for POST requests. What is confusing about that?

I don't find the paragraph confusing per se. It's just that it appears within a section named "targetSchema" and HTTP and hence seems unrelated with the beginning of the section. That's why I mentioned the "content negociation" section. Maybe it's a matter of re-organizing contents.

[handrews]

I don't find the paragraph confusing per se. It's just that it appears within a section named "targetSchema" and HTTP and hence seems unrelated with the beginning of the section. That's why I mentioned the "content negociation" section. Maybe it's a matter of re-organizing contents.

Oh, yeah, that makes sense. It was kind of a 'and here's the exception to using "targetSchema"' thing, which I think made more sense at some point but I either forgot to move it somewhere else or forgot to change the name of the section. I'll figure out which makes the most sense and post a PR for it.

[handrews]

Merged fix in #484 for things not addressed in #476.