How should parameter examples be written?

[chrisradek]

I'm trying to understand whether or not to apply serialization to parameter examples. If I'm following #3041 and the changes added to 3.0.4, it looks like parameter examples should be serialized according to this table:
https://spec.openapis.org/oas/v3.0.4.html#style-examples

So then I'd have parameters specified like this:

parameters:
  - name: foo
    in: query
    required: true
    schema:
      type: string
      enum:
        - blue
    explode: false
    example: ?foo=blue # Instead of "blue"
  - name: colors
    in: query
    required: true
    explode: false
    schema:
      type: array
      items:
        type: string
    example: "?color=blue,black,brown" # Instead of ["blue", "black", "brown"]

However this seems to cause problems for the tooling I've tested with (swagger-ui, spectral, vacuum) and seems to contradict documentation around parameters elsewhere (where the serialization:
https://swagger.io/docs/specification/v3_0/describing-parameters/#parameter-examples

I work on a tool that generates Open API and am adding support for emitting parameter examples, but came across issues around tooling support as part of validation. I'm curious if there are any tools that do work with the serialized examples.

[mikekistler]

This is a very interesting question! My understanding had always been that the example/examples for a query parameter would only contain the value, but now I see why that might not give the whole picture -- in particular for a parameter with explode: true (which BTW is the default for query params in 3.0 and onward).

parameters:
  - name: colors
    in: query
    explode: true
    schema:
      type: array
      items:
        type: string
    example:  # what to put here?

Specifying ["blue", "black", "brown"] as the example for this parameter is incorrect, since you can't use ?colors=["blue", "black", "brown"] in the query string. On the other hand, specifying brown -- which is a valid value for ?colors= -- will likely give an error from the linter as it is not an array.

Hmmm. Are the tools just wrong on this?

[karenetheridge]

[mikekistler]

@karenetheridge I like your interpretation but I don't think the OAS is as clear on this.

In the section you reference, the value field of the Example Object is described as "Embedded literal example", which (to me anyway) isn't clear on whether it is an encoded/serialized or deserialized version of the field.

And the example field of a Parameter Object is similarly vague. It is described as "Example of the parameter’s potential value".

This vagueness is compounded by the wording in the Style Examples section:

The following table shows examples, as would be shown with the example or examples keywords, of the different serializations for each value.

I think a reader could reasonably infer from this that "serializations" of the values are what are expected in the "example or examples keywords".

And while I like the idea of using "externalValue" to show the "serialized value" of a parameter, this is really inconvenient if what I want to show is the serialized value of a query param with explode: true, because I can't put that inline ... I have to put it somewhere else and reference it from externalValue with a URI.

[chrisradek]

.../examples/0/value should be the deserialized version of the data
.../examples/0/externalValue should be the literal (encoded) version of the data as it would appear in the request/response

I don't see that distinction in the spec - the value field says Embedded literal example., and externalValue says A URI that identifies the literal example..

The working with examples section (https://spec.openapis.org/oas/v3.1.1#working-with-examples) also seems to suggest (for parameters) that the serialized form should be used - or at least that's how it reads to me:

SHOULD both match the schema and be formatted as they would appear as a serialized parameter or within a media type representation.

and

Because examples using these fields represent the final serialized form of the data

But again all the tooling I've tested with (which is in no way exhaustive) seems to operate on the assumption that the parameter examples should be using the deserialized version of the data.

[karenetheridge]

I don't see that distinction in the spec - the value field says Embedded literal example., and externalValue says A URI that identifies the literal example..

Yes you're right -- I totally misread that!