Skip to content

Ambiguities Regarding Parameter Example Validation #3041

Closed
Closed
Ambiguities Regarding Parameter Example Validation#3041
Assignees
handrews
Labels
clarificationrequests to clarify, but not change, part of the specexample obj/keywordsIssues with the Example Object or exampel(s) keywords
Milestone
v3.0.4

Description

@fariadev22
fariadev22
opened on Oct 7, 2022

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

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.

Activity

  1. handrews
    added
    3.0.4
    on Feb 28, 2023

  2. handrews commented on Feb 28, 2023

    @handrews
    handrews
    on Feb 28, 2023
    Member

    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.

  3. handrews
    added this to the v3.0.4 milestone on Jan 27, 2024
  4. handrews
    added
    clarificationrequests to clarify, but not change, part of the spec
    example obj/keywordsIssues with the Example Object or exampel(s) keywords
    and removed
    3.0.4
    on Jan 27, 2024
  5. handrews
    self-assigned this
    on Apr 23, 2024

  6. handrews commented on Jun 9, 2024

    @handrews
    handrews
    on Jun 9, 2024
    Member

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

  7. handrews commented on Jun 21, 2024

    @handrews
    handrews
    on Jun 21, 2024
    Member

    PRs merged for 3.0.4 and 3.1.1!

  8. handrews
    closed this as completedon Jun 21, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

clarificationrequests to clarify, but not change, part of the specexample obj/keywordsIssues with the Example Object or exampel(s) keywords

Type

No type

Projects

No projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions