v3.3: describe behaviour when deserializing a multipart with a Content-Type header

[karenetheridge]

This is not really a breaking change, since I think what's described here is intuitively the right thing to do anyway, but as it's a new directive I'd still only add it in 3.3 and not backport it to 3.2.1.

• no schema changes are needed for this pull request

[karenetheridge]

I've pushed another commit that corrects the wording.

[karenetheridge]

rebased

[handrews]

One more minor thing about normative language. I assume since the last comment on this PR indicated just a rebase, that the "Let's make sure we're preserving the guidance" comment has not yet been addressed?

[karenetheridge]

I assume since the last comment on this PR indicated just a rebase, that the "Let's make sure we're preserving the guidance" comment has not yet been addressed?

I looked, and it seemed to me at the time that we were already preserving the guidance, so there was no additional change needed.

[handrews]

@karenetheridge I don't see anything that specifically addresses multiple values in the contentType field and using Content-Type to disambiguate that, but maybe it's in a non-changed block that I haven't noticed or I am otherwise overlooking it? Or do you think it is just sufficiently obvious from the field definition as to not be worth calling out?

[karenetheridge]

This line:

if a Content-Type header is present in the specific part, its value SHALL be used instead of these values

Is this intended to only refer to contentType's default value (calculated from the schema type)? I've never interpreted it that way, instead seeing it as referring to the contentType's explicit value(s) as well as the default.

[handrews]

Oh, I see the confusion now. I read "these values" as applying to the defaults only because that line immediately follows the explanation of default behavior.

But if "these values" includes explicit contentType values, I don't understand the "Behavior is undefined when both this header and contentType are defined but with different values." line. That line (correctly) treats an outright conflict as undefined.

So that leaves:

• default values, including a possible contradiction - I read the first line as treating Content-Type as an override. Which now that I think of it, probably ought to be a SHOULD as a compliant 3.2 implementation could have implemented other behavior such as an error. I'll defer to overall TSC opinion there, though. It's in the murky area, but in 3.2 we usually, and possibly always, used SHOULDs for those.
• explicit value, not a contradiction (although the Content-Type might be more specific than a matching media range). This is the part I was concernd was not being addressed, as it ought to just note that Content-Type disambiguates if contenType holds multiple values.

At least I think. I've gotten turned around on this one so much I don't entirely trust myself at this point.

But if I'm correct, I think all we need is:

• Clarify that the override behavior applies to defaults (if you agree with that) by using something other than "these values" in that line
• Clarify that Content-Type disambiguates multiple values when at least one is a match (since it would no longer be covered by the current "these values" line, if you agree with me here)
• The existing line that declares Content-Type not matching any explicit contentType values is fine as it is
• (TSC decision pending) maybe demote the SHALL to a SHOULD

[karenetheridge]

I just pushed a change to bring back the bit that I had thought was redundant, and tweaked the wording:

-When multiple values are provided for `contentType`, parsing remains straightforward as the part's actual `Content-Type` is included in the document.
+When multiple values are provided for `contentType`, deserializing remains straightforward as the part's actual `Content-Type` SHOULD be included as a header of that part.

[karenetheridge]

At least I think. I've gotten turned around on this one so much I don't entirely trust myself at this point.

:) me too!

After re-reading several times I think your initial inclination to see that line as only applying to the default value is correct.

And, I think we're clear enough now about what to do in all cases:

• neither contentType nor a Content-Type header is provided: use schema inference to determine a media-type to use for decoding
• no contentType, but we have a Content-Type header: use that, and maybe the schema will be invalid due to a weird deserialization, oh well
• one contentType, no Content-Type header: use that
• more than one contentType provided, no Content-Type: might as well just try each one in turn and go with whatever can be deserialized correctly without errors (this is what I'll do when the new schema is released and I can implement multiple contentTypes)
• one or more contentTypes provided, and a Content-Type header: use Content-Type header (I'm not going to generate an error for this, but it might be a runtime warning or lint or something, if the Content-Type isn't contained in the set of contentTypes)

[handrews]

@karenetheridge I think this point:

one or more contentTypes provided, and a Content-Type header: use Content-Type header (I'm not going to generate an error for this, but it might be a runtime warning or lint or something, if the Content-Type isn't contained in the set of contentTypes)

is actually two cases:

• one or more contentTypes provided, and a Content-Type header that matches at least one media range in contentTypes: Use Content-Type (and if relevant somehow, note which media range was matched- idk if that ever matters, though)
• one or more contentTypes provided, and a Content-Type header that does not match any of them: Use the Content-Type but with the same caveats as "no contentType, but we have a Content-Type header" as these are kind-of the same (just implicit default vs explicit contentType

the important distinction is that one of these cases is well-defined, and the other is not. That's the guidance that I have been trying to make sure does not get dropped.

[miqui]

ok with the normative language changes, but lets see about the remaining unresolved comment.

[handrews]

The only reason I included some "gory details" here is that the RFC is very old and its wording on the default assumptions when Content-Type is absent is weird, and I wanted to call attention to that. It's not just that the default MUST be text/plain..., sadly.