Input/output Overlay / OAD document formats (JSON vs YAML)

[handrews]

In PR #246 (fixing issue #236) @baywet asked:

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

Now that I understand more of what he was asking, my answer is:

Conceptually, the format (meaning JSON vs JSON-compatible YAML) of each Overlay, each input OpenAPI Description document, and each output OpenAPI Description document are all completely independent. You can mix and match JSON and JSON-compatible YAML arbitrarily.

My understanding is that tools apply one Overlay document to one OAD document at a time, so this ends up being pretty simple: You need to allow those two input documents to be either format, and you can output the resulting OAD document in either format.

We should make all of that clear. It's not entirely clear to me how much we need to say all of these options MUST be supported, since JSON <-> YAML coversions aren't hard, but... JSON <-> YAML conversions aren't hard, so integrating the right input/output support into tools isn't that burdensome either.

[baywet]

@handrews thanks for moving this topic here.

What do you think of something like this in the format section?

An Overlay document, whether represented in [[RFC8259|JSON]] or [[YAML|YAML]], MUST be applicable to an OpenAPI document represented in either [[RFC8259|JSON]] or [[YAML|YAML]]. Implementations MUST support application across differing formats.

[baywet]

After reviewing my proposal on today's call, I put together #265 to address this.