Openapi-specification: Please reconsider duality of .example object and .examples array ?

[MikeRalphson]

Please could someone provide some background on the decision to have both .example and .examples[] properties on the requestBody, responses and schemas?

It seems to me this might unnecessarily complicate documentation tooling, while the alternative is simply using a one-element array if only one example is provided. Extending an existing definition with a single example would involve more editing when adding a second one.

An operation object does not have both a .tag and .tags[] properties.

I also found the following wording confusing:

SHOULD be in the correct format as specified [in the] parameter encoding

I'm probably missing something.

[darrelmiller]

From my perspective there wasn't a strong motivation for keeping the "example" property. It was primarily for simplicity and backward compatibility. We have added a fair amount of complexity to some objects, there was some reluctance to force example arrays on everyone.
We have made examples and example mutually exclusive, so for tooling it shouldn't be much more than an extra if statement to handle both properties.

The examples/example have been added to the content object, so when tooling people implement it, it will automatically work for requestBody, responses, callbacks, links, complex parameters.
The example has been left in for schemas. Maybe that isn't needed any more now that example objects are now reusable components.

It is possible there could be some streamlining, but if we were to remove example I think it would be more for reducing conceptual complexity, rather than making tooling easier.

[fehguy]

@MikeRalphson does that answer your question? If so please close...

[MikeRalphson]

@fehguy @darrelmiller Thanks for the response. I would however question the need for "backwards compatibility" when there has explicitly been a breaking change in the version of the specification.

There seems to be no other examples of such mental backwards compatibility around servers, requestBodies etc.

I'm not wholly convinced by the simplicity argument either I'm afraid, there is one spec to create, but many tools, each of which would have to take this wrinkle into account.

If it looks like a wart, and sounds like a wart...

If it is unlikely to change, or is still up for consideration outside the public sphere of GitHub issues, then yes, please close.

[fehguy]

Well this was actually requested and should hopefully be captured in the issues. Certainly nobody was creating work _just_ for the sake of creating work.

[MikeRalphson]

I'll have a hunt through the issues.

Certainly nobody was creating work just for the sake of creating work.

I hope I didn't come off as remotely suggesting that.

[fehguy]

No problem at all. I believe the examples arguments were around the requestBody changes

[MikeRalphson]

Looks like Issue 800 is the most relevant. In which @DavidBiesack expressed a preference for the oneOf example / examples. I could find no other requests for this specific feature in the issues.

[DavidBiesack]

I'll just chime in that my preference is strictly for ease of use of the API author. I think many cases one example is sufficient and using example: is very easy whereas using examples: and coding an array is just more tedious. I think tooling can pretty easily account for this and do the transformation for us; that's what computers are good at. Again, this is just my preference - -I tend to side on ease of use for people using OAS.

[MikeRalphson]

Understood, but I still contend that it doesn't smell like any other part of the OpenAPI 3 spec. ;)

[DavidBiesack]

It is a personal preference, I'm not strongly opposed to more uniform implementation (i.e. just examples: [ ]). (I do not think that preserving singular example: syntax just because it was singular in 2.0 is important here.)

[willdady]

I agree with @MikeRalphson. To me this seems overly verbose when a single item examples array would suffice. If the argument for having both is for 'backwards compatibility' then I think this needs to be revisited since 3.0 is strictly _not_ compatible with 2.0. I would argue the cognitive load of understanding the difference outweighs any tediousness of coding an array (literally adding a - in yaml, json slightly more work sure).