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]

A little git archeology shows that this sentence in the Style Examples section of the Parameter Object description of v3.0.4

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

comes from PR #3859 by @handrews. Henry, did you intend by this new language to indicate that the example field should contain the exact values shown in the table? If yes, then am I interpreting this correctly to mean that a query parameter "color" with type: string and style=form (the default for query params) should specify its example as:

example: ?color=blue

?

[handrews]

I've hidden my first few comments replying to @mikekistler as outdated as they are superseded by the proposal further down.

[jeremyfiel]

I'm leaning towards the tooling being wrong here and I would venture to guess there aren't any tools that considerate the default serialization rules either. This may be a unique area of the spec where the output is transformed.

I'm also not sure if the example value should contain the leading ? or not. I would say no, because you are trying to represent the value, not the url syntax and the value.

cc @tatomyr @AlexVarchuk something to consider for example validation and Redoc display of serialized content

[mikekistler]

@mikekistler yes, that is how I interpreted the requirements as previously written.

It's not clear to me that the "requirements" have been clearly expressed or have been understood in the way you have interpreted them.

I searched the OAS specs and the OAS examples on the Learn site to find an example to confirm or dispute this interpretation and found none. I could not find one example of a query parameter that specifies an "example" value (forgive me if I missed it but searching on "example" shows so many false positives!). From this I would conclude that we haven't really been clear about what an example value should be.

If that's right, then I don't think it is unreasonable for tool vendors to have assumed that the example value for a query parameter is just the value for the parameter, without the "key=" embellishment. This is what I always assumed.

Are there examples of OpenAPI descriptions in the wild that assumed the opposite -- that you have to include the "key=" in the example?

[handrews]

@mikekistler

It's not clear to me that the "requirements" have been clearly expressed or have been understood in the way you have interpreted them.

I searched the OAS specs and the OAS examples on the Learn site to find an example to confirm or dispute this interpretation and found none.

This is from example in the Parameter Object in 3.0.3 (I'm ignoring 3.0.4 because I rewrote that part, so of course it says what I think it should say):

The example SHOULD match the specified schema and encoding properties if present. The example field is mutually exclusive of the examples field. ... To represent examples of media types that cannot naturally be represented in JSON or YAML, a string value can contain the example with escaping where necessary.

And for examples:

Each example SHOULD contain a value in the correct format as specified in the parameter encoding.

If we're talking about media types and encodings, then we're not talking about data structures. If the "encoding" is just to JSON, then the example is represented as a data structure for convenience. But otherwise it is to be a string.

Now, the wiggle room I see here is "cannot naturally be represented in JSON or YAML". One could argue that the input data structure is a JSON/YAML representation of the media type. But if that is the case, it's unclear what wouldn't have a natural representation. Raw binary? That would be done with externalValue anyway. To me, the simplest reading is that if it's not JSON/YAML data, you are to show it as a string, with all of the style/explode/content/encoding/etc applied.

[handrews]

@mikekistler

If that's right, then I don't think it is unreasonable for tool vendors to have assumed that the example value for a query parameter is just the value for the parameter, without the "key=" embellishment. This is what I always assumed.

The requirement is a "SHOULD", so technically vendors can do whatever they want anyway. We need to make the SHOULD clear. If vendors want to do something else, they can do that.

[darrelmiller]

Here's my opinion and it is very biased. Example should be the "input value". We are trying to provide value to consumers of the OpenAPI description and having an example of the input value is useful. Having example show what the serialized version of that input value is a whole lot let interesting. There is a huge caveat to my suggestion. It assumes someone uses a URI Template library for generating their URL. It is quite likely that many people/tools do not do that. They try and hand craft their URLs and now the OpenAPI description is not helping to explain how to serialize the parameters in the URL.

Personally, I don't think people should be hand crafting URLs when calling URLs. I do think it is a job of documentation tooling to show what a properly serialized URL should look like. I don't think it is the job of an OpenAPI description.

It isn't completely obvious what we should do in the case of URLs, but consider the a case of a request body for an operation that has a Content-Encoding header with a default value of gzip. Does anyone think the request body example should show compressed content?

[handrews]

@darrelmiller the problem is that we already debated this for 3.0.4 and 3.1.1 and went the other direction based on the text that existed in 3.0.3, which clearly specifies that the encoding SHOULD be applied.

I think the correct thing to do is to let example and the Example Object's value and externalValue remain ambiguous (since apparently it wasn't enough to approve clarifications last release, we have to argue over it again now) including the confusing rules about what can and can't be given as inline JSON/YAML, and add inputValue and outputValue to the Example Object (and the external* equivalents) and allow people to provide whichever works for them. And both of those would have clearly-defined behavior. People migrating from 3.1 could choose whether to leave it in the old ambiguous fields, or migrate it to whichever of the new fields suits their needs.

[hudlow]

As much as it pains me to let implementations direct the spec, it really feels like there is such a strong consensus in implementations that we'll just be introducing pain by trying to fight it in 3.x, and if we introduce another example encoding, it probably should be serializedValue or some such.

@mikekistler asked me what I thought about this, so I tested the most popular linters as measured by GitHub stars:

1. Spectral (2.7K stars): error for serialized example values
2. Redocly (1.2K stars): error for serialized example values
3. Vacuum (767 stars): error for serialized example values
4. IBM OpenAPI Validator (549 stars): error for serialized example values

@handrews I also tested oascomply and it also seemed to require deserialized values in parameter examples. Given its immature state, I'm not sure this is meaningful, but it seems to at least confirm that if parameter examples are supposed to be the serialized form, it's been very easy to get this wrong.

[handrews]

@hudlow Anything OASComply was doing shouldn't be taken too seriously, it was a proof-of-concept, and I never got the example validation working anyway. I think in part because I realized I was doing it wrong.

I think the solution is to add consistent and interoperable fields to the Example Object for 3.2, and let the existing fields just be whatever. We have argued about this I think at least once a year for three years running now. We argued about it for 3.0.4 and 3.1.1 and approved a PR, which people now disagree with despite approving it last year. And I know we argued about it in detail at least once before that, because one part of it was noted as one of the most obscure debates that took place in our slack.

[handrews]

OK here's a revised proposal for dataValue, externalDataValue, serializedValue, and externalSerializedValue, which are more clear than "input" which could go either way (input to serializaion or input to parsing?). The changes to value and externalValue are italicized, except for the deprecation marking which is bold as usual:

Field Name	Type	Description
summary	string	Short description for the example.
description	string	Long description for the example. CommonMark syntax MAY be used for rich text representation.
dataValue	Any	An example of the data structure that MUST be valid according to the relevant Schema Object. If this field is present, externalDataValue, value, and externalValue MUST be absent.
externalDataValue	string	A URI that identifies the data example in a separate document, allowing for values not easily expressed in JSON or YAML. This is usually only needed when working with binary data. The value MUST be valid accordinig to the relevant Schema Object. If this field is present, then dataValue, value, and externalValue MUST be absent. See also the rules for resolving Relative References.
serializedValue	string	An example of the serialized form of the value, including all relevant encoding and escaping. If dataValue or externalDataValue are present, then this field SHOULD contain the serialization of the given data. Otherwise, it SHOULD be the valid serialization of a data value that itself MUST be valid as described for dataValue. This field SHOULD NOT be used if the serialization format is JSON, as the data form is easier to work with. If this field is present, externalSerializedValue, value, and externalValue MUST be absent.
externalSerializedValue	string	A URI that identifies the serialized example in a separate document, allowing for values not easily or readably expressed in JSON or YAML strings. If dataValue or externalDataValue are present, then this field SHOULD identify a serialization of the given data. Otherwise, the value SHOULD be a valid serialization as described for serializedValue. If this field is present, serializedValue, value, and externalValue MUST be absent. See also the rules for resolving Relative References.
value	Any	Deprecated. Embedded literal example. The value field and externalValue field are mutually exclusive. 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. It is implementation-defined whether this value is treated as a data or serialized avalue.
externalValue	string	Deprecated. A URI that identifies the literal example. This provides the capability to reference examples that cannot easily be included in JSON or YAML documents. The value field and externalValue field are mutually exclusive. It is implementation-defined whether this value is treated as a data or serialized avalue. See the rules for resolving Relative References.

This object MAY be extended with Specification Extensions.

Note that the serialized form of query parameters (in: "query" or in: "querystring" does not include the ?, which is part of the URI generic syntax, even though implementations of RFC6570 automatically include it; it is also not part of the application/x-www-form-urlencoded media type, which only covers the part between the ? delimiter and the # delimiter or the end of the URI if no # is present).

---

Picking one of the parameter examples from my now-hidden outdated comment above, plus some other in values, they would now look like this:

parameters:
- name: color
  schema:
    type: array
    items:
      type: string
  style: form
  explode: true
  examples:
    "":
      dataValue: [blue, black, brown]
      serializedValue: color=blue&color=black&color=brown
- name: flag
  schema:
    type: boolean
  examples:
    "true":
      summary: show representation of boolean true
      dataValue: true
      serializedValue: "flag=true"
    "false":
      summary: show representation of boolean false
      dataValue: false
      serializedValue: "flag=false"
- name: usernames
  in: path
  schema:
    type: array
    items:
      type: string
  style: matrix
  explode: false
  examples:
    "":
      dataValue: [handrews, 张]
      serializedValue: ;handrews;%E5%BC%A0
- name: cookie
  in: cookie
  # We can't use `style` because it enforces URI percent-encoding, which is wrong for cookies 
  content:
    text/plain; charset=utf-8:
      schema:
        type: string
      examples:
        "":
          summary: There is no encoding to apply here
          dataValue: 张
          serializedValue: 张
  examples:
    "":
      summary: Show that cookies use base64 encoding
      dataValue: 张
      serializedValue: 5byg
requestBody:
  content:
    image/png:
      examples:
        "":
          summary: Raw binary images are not encoded
          externalDataValue: ./examples/body.png
          externalSerializedValue: ./examples/body.png

[handrews]

This comment thread now just covers the basic proposal to add dataValue, externalDataValue, serializedValue, and externalSerializedValue while deprecating value and externalValue and declaring their behavior to be implementation-defined.

[handrews]

[NOTE: This is split out from the first version of the previous thread, which had too many things in it. This part can be an add-on, but is not needed for the basic proposal above. It could even be done totally separately, but probably doesn't make much sense without the first part.]

In addition to the above, we should allow using examples alongside of content in the Parameter Object or Header Object:

Using the in: "querystring" JSON Path query example from PR #4590, we see that the examples field in the Media Type Object only serializes as far as the given media type, in this case application/jsonpath, making the dataValue and serializedValue identical (you would probably only bother with dataValue in this sort of case).

So in order to show an example of the fully serialized query string contents, we need to allow examples alongside of content, where it is currently forbidden.

parameters
- in: querystring
  name: selector
  content:
    application/jsonpath:
      schema:
        type: string
    examples:
      "":
        dataValue: $.a.b[1:1]
        serializedValue: $.a.b[1:1]
  examples:
    "":
      dataValue: $.a.b[1:1]
      serializedValue: %24.a.b%5B1%3A1%5D

In this scenario, I would likely only use examples in the Parameter Object alongside content, as using examples in the Media Type Object is trivial regarding serialization and not very interesting.

[handrews]

A third part of this would be supporting examples in the Encoding Object. This is potentially the most thorny of the parts, and is techincally independent of the other two (although it doesn't make much sense without the dataValue, serializedValue, etc. part).

---

This third proposal allows examples in the Encoding Object, on top of the new Example Object fields in the first part and allowing examples alongside content in the Paramter and Head

NOTE: I need to think a bit more on the correct serialized form in the Encoding Object- by parallel with the Parameter Object, it should include the parameter names when doing urlencoded, but it's less clear how that applies to multipart.

---

Separately, in: "querystring" has its own concerns. In this example, the last examples could go on either the Media Type Object or (if we adopted the second proposal about examples with content) the Parameter Object, as the result in both cases is an application/x-www-form-urlencoded serialization.

As this media type is (by definition) URL-ready, the Parameter Object implementation MUST NOT apply another layer of percent-encoding. This is just a thing that implementations will need to know about using certain media types in certain places- probably something that we need to put in the media type registry:

parameters:
- name: qs
  in: querystring
  content:
    application/x-www-form-urlencoded:
      schema:
        type: object
        properties:
          metadata:
            type: object
            properties:
              name:
                type: string
          icon:
            type: string
            contentEncoding: base64url
      encoding:
        metadata:
          examples:
            "":
              dataValue: {"name": "2x2 Red"}           
        icon:
          contentType: image/png, image/jpeg
          examples:
            "":
              summary: A solid red 2x2 pixel image
              externalDataValue: ./examples/red2by2.png
              # NOTE: It's possible that this should have `icon=` at the start, need to figure that out
              serializedValue: iVBORw0KGgoAAAANSUhEUgAAAAIAAAACCAIAAAD91JpzAAAABGdBTUEAALGPC_xhBQAAADhlWElmTU0AKgAAAAgAAYdpAAQAAAABAAAAGgAAAAAAAqACAAQAAAABAAAAAqADAAQAAAABAAAAAgAAAADO0J6QAAAAEElEQVQIHWP8zwACTGCSAQANHQEDqtPptQAAAABJRU5ErkJggg%3D%3D
      examples:
        "":
          summary: Example using the dataValue or externalDataValue from each property's unnamed example in the Encoding Object, with JSON whitespace minimized
          serializedValue: metadata=%7B%22name%22%3A%222x2%20Red%22%7D&icon=iVBORw0KGgoAAAANSUhEUgAAAAIAAAACCAIAAAD91JpzAAAABGdBTUEAALGPC_xhBQAAADhlWElmTU0AKgAAAAgAAYdpAAQAAAABAAAAGgAAAAAAAqACAAQAAAABAAAAAqADAAQAAAABAAAAAgAAAADO0J6QAAAAEElEQVQIHWP8zwACTGCSAQANHQEDqtPptQAAAABJRU5ErkJggg%3D%3D

If we did the querystring example with the icon and metadata as a multipart body and did not base64-encode the PNG, we'd need to use externalSerializedValue:

requestBody:
  content:
    multipart/form-data:
      schema:
        type: object
        properties:
          metadata:
            type: object
            properties:
              name:
                type: string
          icon:
            type: string
      encoding:
        metadata:
          examples:
            "":
              dataValue: {"name": "2x2 Red"}              
        icon:
          contentType: image/png, image/jpeg
          examples:
            "":
              summary: A solid red 2x2 pixel image
              externalDataValue: ./examples/red2by2.png
              # NOTE: It's possible that this should be a complete part serialization, including part headers.  Need to figure this out.
              externalSerializedValue: ./examples/red2by2.png
      examples:
        "":
          summary: Example using the dataValue or externalDataValue from each property's unnamed example in the Encoding Object, with JSON whitespace minimized
          externalSerializedValue: ./examples/multipartWithBinaryPart.multipart