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

@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 theapplication/jsonpath example comes in, although perhapsapplication/jsonl would be a better example as the data and serialized forms are different. I can see thatapplication/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 anapplication/jsonl example that would make more sense.

Regardless of where else you useapplication/jsonl, you might also want to shove it into a query string. For... reasons. (this is why I usedapplication/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 theapplication/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 usingcontent 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.

The last force-push is a rebase to resolve conflicts plus one additional commit that removes theLink example because it is better addressed by PR#4740. The Set-Cookie guidance that is mentioned is PR#4748.

Between the ongoing debate overserializedValue in the Example Object and the discussions here, I'm re-thinking how to explain this better. Putting this in draft for now- I might revive it or close it in favor of new PRs.

Closing in favor of PRs#4802 and#4801