Clarify difference between OAS "examples" and JSON Schema "examples"

[darrelmiller]

OAS examples is a map. JSON Schema examples is an array.

[philsturgeon]

Any tips on where to put this?

[kevinoid]

I just ran across this issue and I'm a bit confused. Clarification would be greatly appreciated.

You are probably already aware, but the "In a model" example from the Example Object Examples sub-section of Example Object (in 3.0.2, 3.0.3, and 3.1.0) appears to show an OAS Map[ string, Example Object ] on a Schema Object.

For 3.0.2/3.0.3 this is confusing, since Write Draft 00 doesn't have examples and I don't see the property mentioned as an OAS addition in Schema Object.

For 3.1.0, if examples on Schema Object should be examples from JSON Schema Draft 2019-09, the example would appear to be invalid and should probably be removed from the OAS Example Object section.

[darrelmiller]

That seems wrong to me. There was never supposed to be examples in the schema object. We explicitly chose that so as not to conflict with the examples that was coming in JSON Schema.

Thank you for seeing this. We will review and remove these incorrect examples.

[darrelmiller]

The bad example has been removed. Describing the distinction between examples in a schema and examples in a media type object should be done in the getting started guide, not in the specification.