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.