headerSchema/targetHints vs targetMetaDataSchema/targetMetaDataHints

[handrews]

I've had some feedback while talking up hyper-schema that headerSchema feels a little too HTTP-specific. And it also occurs to me that these fields aren't named very consistently.

Renaming them would produce the following set of keywords for the link target:

• targetSchema
• targetMediaType
• targetMetaDataSchema
• targetMetaDataHints

The HTTP section would still clearly map the metadata fields to headers.

Thoughts, anyone? @philsturgeon @dlax @mokkabonna ?

[handrews]

Also worth thinking is how non-representation operations (e.g. POST) that use submissionSchema and submissionMediaType fit in to this. I think that targetMetaData* makes sense because submissions are still interacting with the target, and the metadata is for that interaction. The submission* part is just due to the payload being unrelated to the target representation. But if anyone has use cases where this doesn't hold up please note them here.

[handrews]

CoAP options might be a good use case to consider. Some of them align with HTTP headers, but HTTP headers are also involved in HTTP-CoAP proxying. And other options, such as Observe, do not have corresponding HTTP headers.

[mokkabonna]

Since HTTP headers both contain meta data about the request and its payload (content-type, content-length etc) and indication of desired server behaviour (accept, prefer etc) the usage of metaData for both might slighly confuse someone using hyper schema over HTTP. Where headerSchema is quite straight forward.

But I understand the desire for the changes.

[philsturgeon]

For the sake of those who aren’t super aware of every single hyper Schema keyword and it’s meaning (✋🏼) can you list each rename, with the from keyword and the to keyword? - foo > bar Im trying to piece it together from multiple emails from these issues and it’s tough.

…

-- Phil Sturgeon @philsturgeon

On Mar 12, 2018, at 07:59, Martin Hansen ***@***.***> wrote: Since HTTP headers both contain meta data about the request and its payload (content-type, content-length etc) and indication of desired server behaviour (accept, prefer etc) the usage of metaData for both might slighly confuse someone using hyper schema over HTTP. Where headerSchema is quite straight forward. But I understand the desire for the changes. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or mute the thread.

[handrews]

@philsturgeon Possible renames include:

targetHints -> targetMetaDataHints
headerSchema -> targetMetaDataSchema

The questions being:

1. Is metaData correct for either or both keywords? @mokkabonna brings up that some HTTP headers are arguably not "meta-data", at least not in the sense of being meta-data about the target resource. I'm not sure that description of / requests for server behavior aren't meta-data, but I haven't figured out how to articulate that thought properly.
2. Is target correct for either or both keywords? In particular, for headers (whether response hints or request schemas) more relevant to submitting data for processing rather than for interacting with the target representation. My thought here is that even with the submissionSchema and submissionMediaType keywords, you are still submitting to the target, so target is fine.

I am confident that Hints (for the expected values in responses) and Schema (for descriptions of possible values in requests) are the correct names. It's what to prefix those two things with that is unclear.

Currently targetHints and headerSchema aren't really even consistent with each other.

[philsturgeon]

Thanks @handrews! This really helps.

In that case, I completely agree with @mokkabonna. Currently the name headerSchema is a bit confusing as its unclear as to if its describing headers onrequest or response.

Using targetMetaDataSchema actually makes this even more confusing, and its not due to losing "header" from the name. Target to me is explaining what you might get back, and submission is explaining what you might want to send. Target Hints confuses that a bit I suppose, so maybe my expectations are a tad off.

submissionSchema and submissionMediaType keywords, you are still submitting to the target, so target is fine.

I dunno, I think submissionMetaDataSchema for request would make more sense, as submissionSchema is describing the body for that same request.

Anyone with me?

[handrews]

Target to me is explaining what you might get back, and submission is explaining what you might want to send.

That's not accurate (although it is a common misconception due to draft-04). Target describes the target. You get it back from a GET, but you send it with a PUT. You send something based on it with a PATCH. Target is not about sending or receiving, it's about the target.

One of the absolute worst effects of draft-04 is that it was confusingly written to the point where people decided that "targetSchema" meant "response" and "schema" (which was more or less renamed to "submissionSchema") meant request, which is absolutely not true.

I dunno, I think submissionMetaDataSchema for request would make more sense, as submissionSchema is describing the body for that same request.

"submission" definitely does no describe the same request. Submission is only about non-representation data being submitted for processing, which is only one kind of request.

target == representation
submission == non-representation

[handrews]

The other names that were proposed at one point were something along the lines of protocolMetaDataHints and protocolMetaDataSchema, or even just protocolHints and protocolSchema.

[dlax]

Is metaData correct for either or both keywords?

I quite like "metadata" and it doesn't seem incorrect to me.

Is target correct for either or both keywords? In particular, for headers (whether response hints or request schemas) more relevant to submitting data for processing rather than for interacting with the target representation. My thought here is that even with the submissionSchema and submissionMediaType keywords, you are still submitting to the target, so target is fine.

I was thinking we might even drop the "target" prefix for these keywords (while inserting "metadata" of course). After all, unless stated otherwise, link attributes concern the "target". No strong opinion though.

[handrews]

@dlax interesting point about dropping target. The meta-data usually is clear on its own about what it concerns. And it's generally protocol-specific and the whole point of these keywords is to get out of the way of the protocol solving problems it already knows how to solve.

Hmm... metaDataHints and metaDataSchema is sounding pretty appealing.