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.

[handrews]

@awwright @dlax @mokkabonna @philsturgeon I'd like to make a call on this and get it into PR. Also pinging @jdesrosiers as the whole protocol-specific contents solution was his suggestion originally!

I think the most promising contenders are either of these pairs:

• metaDataHints, metaDataSchema
• protocolHints, protocolSchema

metaData* seems to be pretty intuitive to people. On the other hand, some of what is described is really more accurately considered control data (e.g range requests, auth). It also might tempt people to put arbitrary "metadata" by whatever definition they come up with in these keywords, which is not what they're for.

protocol* covers anything conveyed through the protocol, which includes both metadata and control data. It also clearly indicates that the contents are protocol-specific, or at minimum protocol-related, which is correct. Can we think of any URI scheme where there would be a use for these keywords but "protocol" would be a seriously counter-intuitive mismatch?

I don't know of any reason that we'd use these keywords with URN schemes like urn:, tag:, tel:, etc. Nor can I think of any usage with data:.

The most unusual case I can think of is mailto:, which technically only indicates how to construct a message and where to send it, but not the protocol. From RFC 6806:

The 'mailto' URI has unusual semantics because resolving such a URI
does not cause an immediate interaction with a server. Instead, the
client creates a message to the designated address with the various
header fields set as default. The user can edit the message, send
the message unedited, or choose not to send the message.

The <hfname>/<hfvalue> pairs in a 'mailto' URI, although
syntactically equivalent to header fields in a mail message, do not
directly correspond to the header fields in a mail message.

I think the answer comes from a bit further down in the spec:

Originator fields like From and Date, fields related to routing
(Apparently-To, Resent-*, etc.), trace fields, and MIME header fields
(MIME-Version, Content-*), when present in the URI, MUST be ignored.
The mail client MUST create new fields when necessary, as it would
for any new message. Unrecognized header fields and header fields
with values inconsistent with those the mail client would normally
send SHOULD be treated as especially suspect. For example, there may
be header fields that are totally safe but not known to the MUA, so
the MUA MAY choose to show them to the user.

This provides a clear split between actual protocol header fields (e.g. MIME) and URI query string fields that more or less map to protocol headers. Those that are provided for in the URI scheme definition are handled there, and go through whatever indirect mapping is appropriate. Those that are directly described for MIME or other aspects of actually sending the email would fall under protocolSchema (or metaDataSchema).

I think that if we can handle mailto: in a sane way, then we're in pretty good shape. And reading over the above, the protocol* name would seem to clarify how mailto:'s weird overlap regarding headers should be handled.

Thoughts?

[philsturgeon]

I understand the reasoning for wanting to talk about protocol instead of metadata, but to me protocol hints sounds like hinting at which protocol to be using, and thats gonna be a source of confusion for many. Metadata might not be 100% appropriate for these other protocols but they feel a bit edge anyway.

[handrews]

@philsturgeon hmm.... you know the original name for targetHints idea was usageHints, but it was deemed too vague, and protocolUsageHints too long.

At this point I have no idea wtf to do with these keywords. All options, including the current ones, have significant detractors, and nothing has clear broad support.

[philsturgeon]

I am fine with "headerSchema" and "targetHints" tbh.

[handrews]

OK, I'm going to leave this open for another couple of weeks, but if no one shows up to champion an alternative, we'll stick with headerSchema and targetHints. It does not seem like any of the alternatives are compelling enough to people to be worth changing it.

[handrews]

We'll stick with headerSchema and targetHints as it's been nearly five months and no one has spoken up.