v3.2: Explain Param/Header/Enc example serialization #4673
Conversation
The rules for this have not been clear, and are not always intuitive. This states and explains them directly and ensures that the Style Examples table matches the rules.
handrews
added
param serialization
|
I have added updates to the Parameter and Header Object examples, as they fit here (and unlike with the Example Object, do not cause the diff to become unreadable). If you would like more examples added, please help get this PR merged and then feel free to open further PRs. There are endless things we could add and I would like to get the existing things updated first. |
|
I have also added a more complex header example, which @karenetheridge I think addresses your concern in this area. |
| examples: | ||
| number: | ||
| dataValue: [12345678, 90099] | ||
| serializedValue: "12345678,90099" |
There was a problem hiding this comment.
Didn't we have in an earlier PR that "<header name>: " would appear in the serializedValue content?
There was a problem hiding this comment.
@karenetheridge yes, and then I was trying to explain it in the TDC call and realized I wasn't sure about it. This is the part that attempts to explain the discrepancy compared to other non-path params:
For query parameters (
in: "query"andin: "querystring") and cookies (in: "cookie"), the parameter names MUST also be shown, as they are determined in part bystyleandexploderather than only byname
The header name is purely controlled by name and never any other field, and the one RFC6570 expansion allowed for it (simple) does not have anywhere for names to go. And finally, while the Parameter Object contains the name field, the Header Object does not, and Header Objects are re-usable and could in theory be re-used for different headers that have the same basic syntax (e.g. RFC8941 structured headers of a particular type). So if we include the name in the header serialization, that becomes very problematic.
Having worked through it all twice, I'm pretty convinced that this is the correct approach for each in value but I'm very open to being proven wrong.
| @@ -2471,6 +2513,42 @@ ETag: | |||
| pattern: ^" | |||
| ``` | |||
|
|
|||
| A `Link` header that, if present, must include links with the standard relation types `self`, `first`, `prev`, `next`, and `last`, as might be used on a paginated collection: | |||
There was a problem hiding this comment.
@karenetheridge I have (hopefully) improved it in the latest commit, which has the message:
Actually ensure each pattern is matched - in the previous way
the example was written, the uniqueItems was not sufficient
as a link with the same rel but different URI would have satisfied
the conditions.
Also, the text says "includes" these rels, so there could be more
entries.
These updates are about header usage in the Response Object.
Actually ensure each pattern is matched - in the previous way the example was written, the uniqueItems was not sufficient as a link with the same rel but different URI would have satisfied the conditions. Also, the text says "includes" these rels, so there could be more entries.
|
|
||
| When showing serialized examples, such as with the [Example Object's](#example-object) `serializedValue` or `externalSerializedValue` fields, in most cases the value to show is the value, with all relevant percent-encoding or other encoding/escaping mechanisms, and also including any delimiters produced by the `style` and `explode` configuration. | ||
|
|
||
| For query parameters (`in: "query"` and `in: "querystring"`) and cookies (`in: "cookie"`), the parameter names MUST also be shown, as they are determined in part by `style` and `explode` rather than only by `name`, and the leading `?` or `&` delimiter MUST NOT be shown, as it is not used in all scenarios. |
There was a problem hiding this comment.
I kind of think the same should apply to in: header. E.g.,
name: token
in: header
description: token to be passed as a header
required: true
schema:
type: array
items:
type: integer
format: int64
style: simple
examples:
one: "token: 1,2,3"
two: |-
token: 1
token: 2
token: 3
(For anyone not familiar, the HTTP requires that the latter serialization be interpreted as equivalent to the former.)
There was a problem hiding this comment.
style: simple puts commas between the serialized values and does not put the name in the serialization, unlike style: form which puts the names in. So the names stay out of the serialization for headers.
The only modification we make to the RFC6570 behavior is stripping off the leading ? or & from form expansion when necessary (including when looking at one parameter in isolation) because they are not always relevant at all, and whether ? or & is relevant varies based on position, which might not always be the same for a shared referenced Parameter Object.
So header serialization cannot show the header name. Further, Header Objects do not include the name, and one could theoretically use the same Header Object for different headers that have the same syntax.
NOTE: This is another PR split out from PR #4647, and makes significant changes to the
styleserialization for headers compared to that PR, and clarifies the other policies that already existed in PR #4647. This should be more consistent than what was there before, as I commented in the last call when I was unsure of header serialization.The rules for this have not been clear, and are not always intuitive. This states and explains them directly and ensures that the Style Examples table matches the rules.