feat: clarifies format interoperability

[baywet]

fixes #236

This pull request aligns the format considerations with the language and structure used in OAI 3.2.0 for better consistency and understanding.

Key differences with 3.2.0 are:

1. I removed the comment about HTTP case sensitivity since it does not really apply here.
2. I removed the note about API requests and responses bodies formats in relation with the document format since it doesn't really apply here.
3. Updated any mention of "OpenAPI" to "Overlay".

Remaining questions:

1. Should we have a note to say that the format of the OpenAPI and Overlay documents MAY be different?

[handrews]

@baywet

Should we have a note to say that the format of the OpenAPI and Overlay documents MAY be different?

What do you mean by this exactly?

[baywet]

@baywet

Should we have a note to say that the format of the OpenAPI and Overlay documents MAY be different?

What do you mean by this exactly?

@handrews I mean that it's not because your Overlay is in YAML that your OpenAPI description MUST be in YAML, and vice versa

[handrews]

@baywet now I'm even more confused- either of them can be either JSON or JSON-compatible YAML, on a document-by-document basis.

[baywet]

Yes, and I just wanted to ask whether we should clarify that a yaml overlay can be used with a JSON openAPI document.

That's because we have a similar clarification for yaml documents with JSON http request/- response bodies in oad

[handrews]

@baywet OK I guess I'm just lost as I don't understand the concern for request/responses either. Requests/responses are whatever media type they are. It is completely irrelevant whether an OAD or Overlay is in JSON or YAML, because we restrict YAML to its JSON-compatible subset. It's like whether the text i UTF-8 or some other character set. It doesn't matter, it's below the level at which we care. YAML is just a convenience for authoring documents that are, fundamentally, JSON in terms of their data model and how they can be manipulated.

[baywet]

@handrews I agree with you, I'm not sure why we need the format note in the OAI spec in the first place. But since it's there, I was asking whether we should have something similar in the context of overlay vs OAI description.

[ralfhandl]

+1, Minor nit

[lornajane]

Previously we mentioned these as being tags and scalar keys. While I'm sure this reference is entirely correct and comprehensive, could we keep the high-level explanation as well to help people understand what kinds of things to look out for?

[handrews]

@lornajane this change brings it into alignment with OAS 3.2. The previous language was not only confusing but actually incorrect. Fortunately, almost no one paid attention to it. The part about tags was particularly baffling, IIRC.

[handrews]

I think the important thing here is to use the same wording across all three specs.

[handrews]

@baywet

I'm not sure why we need the format note in the OAI spec in the first place. But since it's there, I was asking whether we should have something similar in the context of overlay vs OAI description.

Because it's completely independent of those other things mentioned in the OAS? The OAD (or Overlay document or Arazzo, etc.) needs to be either JSON or JSON-compatible YAML, and this section explains that. It has nothing at all to do with any API content whatsoever.