docs: adds a clarification for different formats across documents

[baywet]

fixes #260

[jeremyfiel]

Overlays are not restricted to an OAD. They can be applied to any JSON/YAML document. That should be clearly defined and allowed

[lornajane]

I disagree @jeremyfiel - we are not committing to maintain a generic JSON updating tool here. In fact in the meetings we have discussed that we would like the Overlays to be more OpenAPI-aware, not more generic.

[baywet]

@jeremyfiel :
From the Overlay v1.0 specification

What is the Overlay Specification?
The Overlay Specification defines a document format for information that augments an existing [OpenAPI] description yet remains separate from the OpenAPI description’s source document(s).

If we want to expand the mandate of Overlays, it probably means a major overhaul of the specification itself. I'm not fundamentally opposed to that, but I think this is probably a v2 kind of thing. Not a v1.1.
Additionally, in my latest update, I rephrased things to cover OpenAPI descriptions which might be a single document, or might be multiple documents, fragments etc... (so applying an overlay to an external JSON schema is still possible). I hope that represents the "most flexible" overlays can be today.

[handrews]

@lornajane I agree, Overlays can become more powerful for the OpenAPI ecosystem by leveraging knowledge of OAS/Arazzo syntax and semantics. JSON Patch and JSON Merge-Patch already exist as generic JSON modification systems.

@baywet there might be some subtleties here if "OpenAPI Description" (the "D" should be capitalized) is used, as opposed to just any OpenAPI document (little "d"). Applying to a doccument is intuitive. But if we're applying to OADs, does that mean applying to an entry document applies to all documents reachable from that entry document? (AFAICT Overlays currently work on individual documents, my apologies if I am misunderstanding).

[baywet]

@handrews you are correct, the overlays "don't understand" the semantics of Descriptions which can aggregate multiple documents. Or at least it's not clearly called out/buried under multiple layers of specifications. I think that if we could update the wording to say "this can apply to OpenAPI documents, JSON schemas (as a schema alone in a file), and OpenAPI document "fragments" (might have a different name, but I was under the impression we could leave an OpenAPI operation alone as a root node for reusability and it was a valid thing). We'd cover all the use cases of OpenAPI while refraining from expanding to "other use cases" which were clearly not the initial plan.

Thoughts?