The examples keyword is not supported inside schema

[philsturgeon]

Relates to stoplightio/prism#722

This example of examples is a mistake.

[philsturgeon]

@darrelmiller can we get this up on the agenda for next week or do it kinda sooner before it gets lost in the deluge of other PRs.

[webron]

Yup, these were probably left over from the old interactions we had around the Example Object. Good to go.

[earth2marsh]

Good catch, @philsturgeon , and your edits to remove the faulty examples LGTM.

I have one concern though, which is that while an examples object is inappropriate to appear within a schema, it is appropriate within a parameter object. By removing the erroneous example there is now a void left of having no valid parameter example of the examples object.

If there's a good reason for why we shouldn't have one of those, then let's keep moving forward with a merge, but otherwise, this would be improved by adding that IMO.

[philsturgeon]

@earth2marsh every day is a school day!

What does this mean. In the Property Object it says "example of the media type", but... it's a parameter? Is this actually a named objects array like in the Media Type Object? If so, AGH! If not, AGH! ?

[earth2marsh]

Huh, that strikes me as odd, for both example and examples. The feeling of, "WTH were we thinking when we wrote that?" encroaches...

[darrelmiller]

@philsturgeon Even parameters can be described using Content objects and therefore they can have media types. It's a bit weird, but then people insisted on being able to shove objects in the URL.
text/plain is a valid media type. For simpler parameters that just use style and schema, there is wording that says what example and examples should do:

For more complex scenarios, the content property can define the media type and schema of the parameter. A parameter MUST contain either a schema property, or a content property, but not both. When example or examples are provided in conjunction with the schema object, the example MUST follow the prescribed serialization strategy for the parameter.

[philsturgeon]

@darrelmiller hey I’m not sure about the words here, it doesn’t make any sense. What do examples have to do with media type? Where is text/plain coming from? Multiple examples are given arbitrary names, nothing to do with media types? What is happening I’m scared.

[darrelmiller]

@philsturgeon Media types are a description of how to convey meaning in a series of bytes. Parameter values in a URL are a series of bytes that follow some kind of format. The only difference between values in the URL and values in the HTTP payload is the payload is usually bigger.... but not always. When we moved the location of examples in V3, we changed the key from being a media type identifier to just be any old identifier that can be used to identify a scenario.

Let me try and provide an example:

openapi: 3.0.2
paths:
  /SomeRecentData:
     get:  
       parameters:
        - name: since
           content:
             text/plain: {}
           examples:
              minutes: "20m"
              hours: "3h"
              dateTime: "2009/10/11T11:59:00"
       responses:
         200:
           description: OK

So, what happens you might ask, if somebody defines two different media types. There is no way of doing content-negotiation on parameters. There's no content-type header for parameters. The reality, is, don't do it, unless you want to start sniffing parameter values to guess whether they are JSON or XML for example. We spent a silly amount of hours trying to figure out a cleaner way of letting people do ridiculous things in URLs, but eventually, we decide that common sense would need to prevail. If you really, really need to use content objects to describe parameters, please don't use multiple media types.

[philsturgeon]

Ok so this explains my confusion perfectly, thank you @darrelmiller.

When we moved the location of examples in V3, we changed the key from being a media type identifier to just be any old identifier that can be used to identify a scenario.

Yeah so examples contain arbitrary values keyed by arbitrary strings, and there is no content negotiation. Great, The only connection between Media Types and Parameters is... examples used to be tied to media types as keys but they aren't anymore. That makes me think we should change the wording.

I switched the wording, lmk what you think.

[earth2marsh]

Thanks for the changes, Phil. I made some super-minor edits, and this now LGTM.

[philsturgeon]

@darrelmiller @MikeRalphson can somebody merge this one now it's approved?

[philsturgeon]

@MikeRalphson thanks for merging #2054, this is a very similar one: just updating an example.

@OAI/tsc any concerns with this one?

[mindstretch23]

@darrelmiller Sorry guys for this dumb question...I read above very carefully to try and answer but need a little help...

Does this PR mean that we can now use examples (plural) within the components section (previously unsupported)?