-
Notifications
You must be signed in to change notification settings - Fork 9.1k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Ambiguities Regarding Parameter Example Validation #3041
Comments
See also this Slack thread which discusses whether examples should be shown pre or post-encoding. @kevinswiber noted:
@darrelmiller noted:
|
As you can see in PR #3893, I dug into the history and it looks like SHOULD is correct. |
PRs merged for 3.0.4 and 3.1.1! |
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:
![Conflict](https://user-images.githubusercontent.com/20472892/194554852-e84cd65a-ad70-4338-895e-bc54fc18c5e8.PNG)
Let's assume that a parameter
example
is present next to aschema
property.This indicates that the example is RECOMMENDED to be valid against the schema and encoding. By encoding I'm assuming it implies
style
,explode
andallowReserved
.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.
The text was updated successfully, but these errors were encountered: