Proposal: Allow/Recommend/Force that JSON/Yaml examples be encoded as a string

[SJrX]

FYI there was a slack thread where this was mentioned and I'm just bringing it here, several months late.

In the spec today it mentions that:

To represent examples of media types that cannot naturally represented in JSON or YAML, use a string value to contain the example, escaping where necessary.

To me that sort of implies that JSON and YAML cannot be encoded as a string., I found this thread: OAI/OpenAPI-Specification#3289 that kind of confirms it, thought it links to another issue, that links to a thread that doesn't seem to be a thread.

I was curious about proposing that it be allowed to be string encoded. I guess the main reasons would be:

1. As someone who occasionally dabbles in processing docs and stuff, it seems like examples of the API shouldn't be part of the spec (e.g., if say I'm visiting nodes in the tree, this should just be a complete example, and probably shouldn't be processed) </handwaving> . For example I might want to format and style an example differently than the spec. Some other tools for instance like yq which we use to post process them, just completely obliterate the examples, but I assume it will not care that I used JSON syntax and convert it to YAML.
2. This came up for a couple reasons for our projects:
   • We were doing something fancy with our IDE, where we can use language injection (JetBrains IDEs), so we can edit and treat it differently, and also style it differently (see attached screenshot, the one on the right in my view is nicer, because it looks like JSON, and we are describing a JSON API).
   • In some specs our examples were broken because devs were writing JSON responses in Yaml, which in my opinion, makes it harder to see oddities, if you are use to interacting with the API and seeing JSON.

[SJrX]

@handrews brought up some concerns in the thread.

Since the string would just be interpreted as a single string, we'd need some way to tell when it was intended to be parsed as a document instead. Which could perhaps be done as a backwards-compatible added field, but it would be a complication for a use case that seems less common.

This sort of logic can work, but it adds complexity and ambiguity, and the more such things are in the spec the harder it is to implement. We're trying to move in the direction of less ambiguity, fewer fields that do multiple things or have variable types depending on context, and generally less complexity in processing.

Any one such decision isn't necessarily prohibitively difficult, but they add up. And it's already a very complex specification to implement fully.

I have zero experience developing specs and only an novice level understanding of working with the complexities of OpenAPI. I guess to me the simplest thing to do, would be potentially a backwards compatible change, where you make a new field (that is always) a string value, and you always interpret it as its content type.

This would provide a clean separation between the specification document, and the example document. It would be easier for processing and tools to manipulate clearly (if for example you are styling or bundling documents with redocly, or resolving yaml anchors, the examples would not be touched), today if you have a comment in the Yaml example it's likely interpreted as a comment of the spec by most tools, and tools can't really know whether a comment in the example is part of the example or part of the openapi spec. I think just forcing everything to be a string would be cleaner.

Providing a new key would likely provide an easy migration path since.

Anyway just some thoughts.

[handrews]

@SJrX This came from the complicated way that the Example Object's value field (and the singular example field that is a shorthand for examples with one Example Object that just has a value field) is defined.

For OAS 3.2 we now have dataValue (which is always represented in the JSON data model) and serializedValue (which is always a string). So you should be able to do what you want there.

The value field was always supposed to semantically represent the serialized value. But for JSON and YAML it allowed a syntax shotrcut that made it look like a non-serialized value.

So for JSON/YAML you can still use value as it doesn't really matter unless you want to stuff it into a string, in which case you can use serializedValue. We have deprecated value for non-JSON/YAML formats because it was implemented inconsistently, with many implementations treating it more like dataValue than like serializedValue with weird handling of JSON/YAML.

[SJrX]

Ah thank you, and sorry for the delay in filing this issue (I only checked 4.0 for changes). I guess you can close it.