Ambiguities Regarding Parameter Example Validation

[fariadev22]

As part of a spec validation related research, I have run into some confusions in the OpenAPI v3.0.3 specification document Parameter Object section, in particular the one shown below:

Let's assume that a parameter example is present next to a schema property.

The example SHOULD match the specified schema and encoding properties if present.

This indicates that the example is RECOMMENDED to be valid against the schema and encoding. By encoding I'm assuming it implies style, explode and allowReserved.

When example or examples are provided in conjunction with the schema object, the example MUST follow the prescribed serialization strategy for the parameter.

Here, we are told that it is MANDATORY for the example to be valid against the serialization strategies specified for the parameter. I'm assuming again that the serialization strategies implies a combination of schema + style + explode at the very least. At least, that is what I understood from the rest of the text in this section and examples.

The two statements are clearly clashing with each other as one is making something mandatory while the other is simply recommending things. I'm using this section for interpretation of the words SHOULD and MUST.

Is my understanding of things correct or have I missed something? Any clarity on this would be much appreciated.

Thank you.

[handrews]

See also this Slack thread which discusses whether examples should be shown pre or post-encoding.

@kevinswiber noted:

Just wanted to chime in and say examples is better-specified than example on the Media Type object and I think is a better pattern to use anyway.

That said, the value property on the Example Object (used in examples) states:

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.

However, with the media type being application/json and using the Example Object's logic above, I would think the example value should not include extra quotes. The type string is perfectly capable of being serialized to JSON. It works in key-value pairs just fine. A string is valid JSON. I do think the tooling should add the quotes in this case.

But this is definitely teetering on an edge case of an edge case!

@darrelmiller noted:

To pile on here to this delightfully arcane thread. I agree with the conclusion that the value in examples can be natively expressed as JSON and the URL serializer should contain the string value in quotes to accurately represent it as JSON in URL parameter value.

[handrews]

As you can see in PR #3893, I dug into the history and it looks like SHOULD is correct.

[handrews]

PRs merged for 3.0.4 and 3.1.1!