contentEncoding is a confusing term

[ioggstream]

Question

the use of contentEncoding, contentMediaType from here is very confusing
considered the use of json-schema in OAS3.1 spec
https://json-schema.org/understanding-json-schema/reference/non_json_data.html

I suggest to use another term instead of content and contentEncoding.

Suitable values could be stringEncoding or objectEncoding... anything that doesn't remind http :)

[handrews]

@ioggstream we try not to change existing keywords without strong reasons. Many formats have things named around encodings and media types and those names often collide. If we try to match OpenAPI we'll be confusing with someone else. There is no universal answer.

Separately, I wrote the comments on JSON Schema's content* keywords in OAS 3.1, and I did not do a great job. I am working on a patch for OAS 3.1.1 that will hopefully be more clear.

Regarding Understanding JSON Schema, if there are improvements you want there, you should file them under its repo. @jdesrosiers is working on updating it.

[handrews]

@ioggstream we could definitely do better by explaining the derivation of the keyword in the spec. We point to some RFCs but a one-liner "this is analogous to MIME's Content-Transfer-Encoding rather than HTTP's Content-Encoding" would help a lot, probably.

[ioggstream]

I think we should spend some time (both in OAS and here) to understand how this kind of functionalities are expected to work together and eg: if the examples we provide with the schema must be "encoded" or not.

For example, what happens when I have contentEncoding in the schema and in OAS I have application/form-urlencoded? Is the property encoded twice? For now it's just brainstorming...

[handrews]

@ioggstream there is an extensive section of the OAS specification dedicated to the form submission media types.

While it may look confusing at first, there is less going on here than people think. You have a representation of a resource in some media type. You parse the document into an internal representation that is more or less compatible with JSON Schema (this is why OAS does things like explain how to map multipart forms into array data structures - b/c that's what JSON Schema understands). Then you apply the schema.

Each step happens in isolation, unaware of the others. There isn't an interaction.

Keep in mind that contentEncoding is an annotation. It doesn't do anything. It just says that "this string here has content in it that is encoded with this encoding", and it's up to the application (in this case OAS and its tooling) to figure out what to do with that information. JSON Schema doesn't care- that's the entire point of annotations. To provide information to applications so that they can use it as they see fit, because there is no one true use case for these things that JSON Schema can lock down.

[handrews]

In particular, contentEncoding and contentMediaType do not validate that the string described is actually an instance of that media type encoded with that encoding, due to both security and performance concerns. The application has to take that information and decide whether to decode/parse and how to handle the security implications of that action, which are highly media-type and usage-specific and not something JSON Schema can dictate.

[handrews]

I'll make PR clarifying this side of things to the extent that that is possible. The larger work is on the OAS side, which I'll get to at some point.

[Relequestual]

@ioggstream Does the PR clarify the issue for you?

[ioggstream]

@Relequestual sorry for the delay, it clarifies the origin thanks! If it's possible, I'd like to have some more time to proof-read the complete text. Thanks again for asking, R.

[Relequestual]

@ioggstream I'll leave this open for another 7 days, and close then if you haven't done so already =]

[ioggstream]

@Relequestual PTAL #1150 In the meantime I'll close this since it's generally ok.