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]

See PR #4647 for more details.

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.

[LasneF]

a personnal opition would be to not go to depreacted but just to precise the that value is the dataValue concept

this would be more seen as an extension versus a change (as deprecation is a change in a way )

one of the concern is tooling practices to raise warning, this would means by that this will generate millions of warning in CICD around the world.

i know it is not super smart ,can be seen as changing the field nature , or just a precision

between the two, measuring the impact i think no deprecation for 3.2 will push for a better adoption

[handrews]

I've split the deprecation discussion out into:

• v3.2: Should the value and externalValue fields be deprecated? #4660
• v3.2: Should the example field be deprecated (Parameter, Header, and Media Type Objects) #4661

[handrews]

See PR #4648 for more details.

[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

[hudlow]

I think this proposal goes a long way toward solving a very real set of problems, and I am deeply appreciative of the effort that has gone into it.

That said, I believe serializedValue has taxonomical (if not practical) problems that echo the problems we're trying to solve, just at a lower level.

One way to describe the original problem (with a few simplifications) is thus:

1. Examples serve to clarify the meaning of an API definition on two levels: semantics and syntax.
   1. Semantically, if I see a name field which is a string, an example showing dhudlow versus Dan Hudlow can be clarifying as to what the field is for. In theory, if you can read and understand the description of the field (stating that this is a case-insensitive alphanumeric screen name), the example is superfluous. (In practice, we all know examples to be useful.)
   2. Syntactically, if I see a tags field which is an array, an example showing ["staging", "public"] versus { items: { '0': 'staging', '1': 'public' } } can be clarifying as to how a schema is actually instantiated. In theory if I read and understand the specifications for the data type and schema language (defining the JSON grammar and what JSON instances a schema describes), the example is superfluous.
2. Historically, we haven't really defined which problems examples in an OpenAPI definition are meant to solve, but we can make some inferences. For example, we can infer that an example within a JSON Schema is suitable for clarifying both semantics and what JSON instances a schema describes, but not suitable for clarifying the JSON grammar since a consumer of a JSON Schema is expected to
   first parse (deserialize) the schema. This seems like a reasonable tradeoff! JSON is much more likely to be already understood than JSON Schema or certainly the semantics of the data a particular schema describes.
3. But OpenAPI describes more than JSON documents! It describes headers and paths and bodies and query strings! It also supports describing non-JSON data with JSON Schema! This creates a tension for examples because if we use JSON-native "logical" values, we get all the benefit of clarifying semantics, and the most flexibility in doing so. (When we consume the API description, we can choose the best way for formatting the logical value and when we, for example, generate code from the API description, we can re-use the logical value in a context abstracted away from the HTTP API.) But the mechanics of how a logical value maps to serialized value may not be well understood, so there is also benefit to having a more literal example value that can clarify the serialization syntax in addition to clarifying the semantics. The shortcomings of logical example values come sharply into focus when there are a lot of different possible serialization grammars for the same logical value, as is the case for parameters and especially for query parameters.
4. We have been mired in ambiguity about which of these kinds of content the value and externalValue properties of the Example Object are supposed to contain but, again, both approaches are useful in their own ways.

So we want separate logical and literal example values! This should ensure that any two literally different protocol-native serializations representing the same logical value will still have different literal example values.

Let me reiterate one point from above. The reason "value": { "name": "Dan Hudlow" } serves as a logical and not a literal JSON example value is that it's "single-serialized" — I'm conveying it within a JSON document, as a JSON value, and to access it I need to deserialize the JSON document and when I do that I will also deserialize the example value and be left with an in-memory data structure. I'll have no idea how it was serialized; for example, whitespace choices are entirely opaque to me.

So what if I do this? "value": "{ \"name\": \"Dan Hudlow\" }". Now when I parse the document containing this value, I'll have access to the string { "name": "Dan Hudlow" } which, notably, is itself JSON and preserves specific serialization choices, like whitespace.

Except... deceptively, this is just like the first example, and the JSON serialization has actually already been replaced with an in-memory data structure! In the first example, that in-memory data structure is generally going to be something like an environment-native struct or object or dictionary or hash. In the second example, the in-memory data structure is an environment-native Unicode string — more precisely, an environment-native vector of Unicode code points.

We still don't know how it was serialized.

Now the objection here might be "Wait, but any vector is a serialization, we can just say we're operating at the Unicode layer, not at the byte-vector layer!"

This would be a reasonable stance to take if we were in a context where (1) every string was Unicode and (2) the Unicode encoding was opaque.

But we're not, in a couple of clear ways:

1. HTTP message request targets (URLs) and HTTP message fields (headers and footers) are US-ASCII, not Unicode.
2. HTTP message contents (née "bodies") are byte vectors whose encoding varies and can be specified in OpenAPI.

As a consequence, if we (naïvely) use a JSON string to carry a literal example value, different serializations will have still have equivalent literal example values.

In other words, there are serialization distinctions that we are still unable to express:

content:
  text/plain; charset=utf-8:
    examples:
      "":
        serializedValue: hello world
  text/plain; charset=utf-16:
    examples:
      "":
        serializedValue: hello world

We also have a situation where we can express something that doesn't make sense:

name: sport
in: query
examples:
  "":
    serializedValue: ⚽︎

There are mitigating factors! UTF-8 is lingua-franca-encoding of JSON and probably of text-based HTTP message contents more broadly; there probably isn't a lot of demand to differentiate examples for other encodings; UTF-8 is a superset of US-ASCII; well-formed UTF-8, UTF-16, and UTF-32 representations map to each other 1:1.

But I still think we need to confront two issues head-on in the spec:

1. Unless we defined serializedValue to provide a representation of a byte vector (like a base64 encoded string, an array of integers in [0, 255]) then "serialized" is a misnomer in a context that deals with byte-level serialization.
2. We need to define how serializedValue values are serialized and what makes a serializedValue value compatible or incompatible with a usage point. For example, presumably "⚽︎" is an invalid value in a parameter context. But is it okay to use a non-external serializedValue for non-UTF-8 content at all?

Here's are some possible solutions that would resolve these issues, in my mind:

1. Rename serializedValue to unicodeValue and specify that:
   1. For parameter contexts, only the first 128 Unicode code points are permitted, and the value would be serialized as ISO 646 ASCII (or UTF-8, which is equivalent).
   2. For content (body) contexts, unicodeValue is only permitted for media types using one of the Unicode encodings, and the value would be serialized as whichever encoding it's applied to.
2. Rename serializedValue to literalValue and specify that:
   1. The value would always be serialized as UTF-8.
   2. For parameter contexts, only the first 128 Unicode code points are permitted.
   3. For content (body) contexts, literalValue is only permitted for UTF-8-encoded media types.

In any case, I think externalDataValue and externalSerializedValue are superfluous and only serve to muddy the waters here. An external value is always going to have made serialization decisions; it cannot really be merely a logical value; as such, there should be no problem simply clarifying the existing externalValue and avoiding adding these two new fields.

Also, if you can't tell, I think logicalValue is a better name than dataValue. 😄

[handrews]

@karenetheridge this paragraph from RFC9110 §5.5 makes me reluctant to enforce ASCII on headers:

Field values are usually constrained to the range of US-ASCII characters [USASCII]. Fields needing a greater range of characters can use an encoding, such as the one defined in [RFC8187]. Historically, HTTP allowed field content with text in the ISO-8859-1 charset [ISO-8859-1], supporting other charsets only through use of [RFC2047] encoding. Specifications for newly defined fields SHOULD limit their values to visible US-ASCII octets (VCHAR), SP, and HTAB. A recipient SHOULD treat other allowed octets in field content (i.e., obs-text) as opaque data.

That's a lot of SHOULDs and "usually"s. And since it's not outright forbidden to go outside of US-ASCII, you know someone out there does it.

There are other SHOULDs elsewhere, like this from the Cookie RFC:

To maximize compatibility with user agents, servers that wish to store arbitrary data in a cookie-value SHOULD encode that data, for example, using Base64.

AFAICT the ABNF restricts to a subset of US-ASCII but apparently they also thought it worth advising base64 encoding? (note- not URI percent-encoding).

So I'd hesitate to lock that down in a validation schema (insert rant about how I wanted us to have a linting schema for this sort of thing...)

[karenetheridge]

Sure, HTTP messages can contain bytes outside the ascii range. You can certainly embed a raw jpeg in an http message without uuencoding it. But how would that be represented in a serializedValue field inside a json document? It's not that it's a bad idea - it's that you physically can't. That's why my original suggestion was that we use spec language reminding the user of this restriction.

Yes, the actual schema restriction would be better put in a linter. You can do anything you like in an OAD whether it makes sense or not. Non-ascii characters in externalValue can never actually match anything found in an HTTP message, so a linter should call that out as wrong.

That reminds me that we need to add an entry in the format registry for ascii strings.

[handrews]

@karenetheridge there are a lot of bytes that are not ASCII but are representable. I'm talking specifically about the headers and citing RFCs that indicate that there may be non-ASCII characters involved, largely for historical reasons. But according to current RFCs, nested multipart/mixed is deprecated, but two people have requested it in the last few weeks from actual usage. So we can't block historical usage.

[karenetheridge]

I don't think you were understanding my original point so I'm going to stop here.

[handrews]

@karenetheridge looking back over this I suspect that GitHub's tendency to splice out intermediate comments and make you expand them is a culprit here, because this comment does not match its immediate predecessor and I'm no longer sure what it was responding to. :-/

[handrews]

I have filed several issues and PRs to move various parts of this to conclusion:

• v3.??? Data vs Serialized Examples in Example Objects #4647 [Now split into...]
  • v3.2: Add data vs serialized Example Object fields (Revised) #4671
  • v3.2: Example Object example updates for new fields #4672
  • v3.2: Explain Param/Header/Enc example serialization #4673
  • (more example updates forthcoming)
• v3.2: Allow Parameter/Header "examples" field with "content" field #4648
• v3.2: Decide on names of new Example Object fields #4658
  • @mikekistler @lornajane I have added this as a release-blocking issue to Prepare 3.2.0 and 3.1.2 releases #4595 so that we can merge this PR with the current names while we keep debating the permanent names. Let's not keep this held open once we agree on the behvior
• v3.1+: Should new guidance be given for example and the Example Object's value and externalValue? #4659
• v3.2: Should the value and externalValue fields be deprecated? #4660
• v3.2: Should the example field be deprecated (Parameter, Header, and Media Type Objects) #4661
• v3.1: Should we change the "?" in the style example table (again)? #4662
• v3.1+: Should we change how non-schema examples "override" schema examples? #4664

[handrews]

Closing due to all of the issues and PRs listed in the previous thread- closed-but-not-merged PRs should link to the later PRs that were merged.

[karenetheridge]

I'm very pleased we got to a place where all usecases can be fulfilled! This is a huge feature in 3.2 and IMHO should get top billing in the release announcement.

[lornajane]

I'm writing the release announcement and giving a talk about the 3.2 release, can you help me to articulate why this part is so great?