v3.2: Allow Parameter/Header "examples" field with "content" field

[handrews]

NOTE: This is a companion to PR #4647 that just adds to where we can use Example Objects as the second part of the three-part proposal. It is written assuming that PR would be merged because that makes the benefit more clear, although it could technically be done even without that PR. But that would be less useful since tools do not support the serialization rules for the old example fields.

Parameter and Header serialization is complex, particularly when using the content field to use a Media Type Object.

In such scenarios, the serialization occurs in two steps: The first step is to serialize the data to the media type, which can be captured by the examples field of the Media Type Object.

The second is the encoding/escaping of the media type document for use in a URI, HTTP header, or other location with its own rules.

Sometimes the part needing illustration with an example is at one level, sometimes at another, and sometimes it is helpful to show both.

For simplicity, the "data" examples are always treated as the overall input data, so they would be the same at both levels. This is also because it is not always possible to show each step, particularly when there are binary serializations. This allows showing either step (or both steps) with both data and serialization, depending on what makes sense for the use case.

• schema changes are included in this pull request
• schema changes are needed for this pull request but not done yet
• no schema changes are needed for this pull request

[handrews]

Rebased with only minor conflicts (Git getting confused by adjacent changes, not multiple changes to the same line).

[ralfhandl]

Why twice examples with the same data and serialized values? Please add explanation what this is supposed to demonstrate, or reduce to one occurrence of examples.

[handrews]

@ralfhandl As noted on lines 1172-1174, the point of this is to show that you do not re-percent-encode the already-percent-encoded application/x-www-form-urlencoded media type. This is in contrast to other media types that would not be percent-encoded in the Media Type Object's examples, but would be percent-encoded in the Parameter Object's examples, which is shown in the next example.

I will figure out a better way to frame / show this.

[ralfhandl]

What's the point of this inner examples? As an example for the parameter it is useless and misleading as it shows a serialized value that is not valid for the paramter. It is technically allowed there, and valid for the schema without its context, and also "academic" and not a best practice we want people to adopt.

[handrews]

It is correct for the Media Type Object, which is the context of this Example Object. It shows an intermediate serialization step. It pairs with the previous example, but I will work out a better way to present this.

[handrews]

@ralfhandl I have not yet re-worked this, but there is also a way that this fits with PR #4728 that I just submitted. While the use case holds with or without that PR, its easier to see if you can re-use all of the Object types involved.

Basically, sometimes you might want to show examples at one level, and sometimes at an another. There are two levels here:

• The Media Type Object, which does not show any special encoding or escaping, just what the media type requires
• The Parameter or Header Object, which shows the special encoding/escaping/formatting required by the target location (some part of the URI or some or all of an HTTP header)

Showing two steps of serialization

This is where the application/jsonpath example comes in, although perhaps application/jsonl would be a better example as the data and serialized forms are different. I can see that application/jsonpath is confusing because at the media type level there's no difference and why would you bother showing that? But I think somewhere in all of these PRs there is an application/jsonl example that would make more sense.

Regardless of where else you use application/jsonl, you might also want to shove it into a query string. For... reasons. (this is why I used application/jsonpath- it actually makes sense in a query... but people use things in all sorts of weird places so.. idk what is the best example here). Anyway, at the Parameter Object level, you want to show the percent-encoding and any other parameter-specific serialization behavior.

With the application/jsonl now you have two non-trivial layers of serialization, and you actually might want to show both just to make it easier to understand. Jumping straight to something with half the characters percent-encoded requires a lot of mental gymnastics. Showing each step is advantageous.

The special case

There is also a special case: application/x-www-form-urlencoded includes, as part of its definition, URI percent-encoding. Part of what we need to show here is that if a media type does something like that, we do not apply the encoding twice. I was showing that by showing that the examples are identical at both levels.

As you note, you almost certainly would not do that in practice, although if you're assembling various re-usable components as #4728 allows, you might end up doing that more-or-less by accident.

It's probably worth adding a specific requirement along the lines of "Media types that already require URI percent-encoding MUST NOT be percent-encoded a second time when using content to specify URI parameters" (and possibly similar language about headers, although encoding and headers is a whole different mess). Then we wouldn't need such a weird example.