OAI
v3.2: Allow Parameter/Header "examples" field with "content" field
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
- [X] schema changes are needed for this pull request but not done yet
- [ ] no schema changes are needed for this pull request
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 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.
The last force-push is a rebase to resolve conflicts plus one additional commit that removes the Link example because it is better addressed by PR #4740. The Set-Cookie guidance that is mentioned is PR #4748.
Between the ongoing debate over serializedValue 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.