v3.1+: Should new guidance be given for example and the Example Object's value and externalValue?

[handrews]

These fields have usually been interpreted by us as requiring serialized values, but this is called into question on an (at least) annual basis (2022, 2023 (mostly on Slack), 2024, 2025).

There are several causes of the confusion:

• Some find the wording (whether in 3.0.4/3.1.1 or earlier releases) specifying that these are encoded/escaped/serialized values unclear
• There is debate over what is or is not "easily represented in JSON/YAML," which can result in tools parsing a string that was intended to just be a string, or failing to parse a string that was intended to be a serialization of a more complex structure
• There is debate over what things like parameter names are or are not included in the serialization

@hudlow surveyed some implementations and found that:

• Spectral (2.7K stars): error for serialized example values
• Redocly (1.2K stars): error for serialized example values
• Vacuum (767 stars): error for serialized example values
• IBM OpenAPI Validator (549 stars): error for serialized example values

@mikekistler has suggested clarifying these and recommending something based on how tools actually implement them.

@handrews has suggested just declaring them "implementation-defined" in 3.2 and leaving things as they are in 3.1, partially out of concern for what can be done in a patch release.

[mikekistler]

It occurred to me after the meeting today that there may be another cause of confusion worth noting. The example field in a Schema Object (added by the OpenAPI JSON Schema vocabulary) is defined as:

A free-form field to include an example of an instance for this schema.

So it is understandable that giving example a different meaning when it appears in a different context might create confusion.

[handrews]

@mikekistler this is probably why the non-Schema example (and the Example Object) were supposed to be serialized values. Because you could put a data value example in the schema. Which would be an argument in favor of just re-emphasizing the original purpose of the non-Schema example fields, but we seem to have decided against that. It also makes the "override" strange, but I forgot to file a separate issue for that which I will do.