v3.2: Explain Param/Header/Enc example serialization #4673
Conversation
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. |
src/oas.md
Outdated
| @@ -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.
There was a problem hiding this comment.
Assuming the application/linkset PR gets accepted, this example is obsolete, but I can show a similar technique with Set-Cookie, which is also good because it has weird serialization requirements which we need to address for examples, which I will do. RFC9110 directs implementations to handle Set-Cookie as a special case, so I will follow that guidance and describe how to work with it rather than trying to change anything else to accommodate it. Stay tuned...
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.
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.
The `Link` header is now addressed in another PR. Make the first example a real header instead of an `X-`. Also provide a link to the Header Object for special cases that will be documented there in other PRs.
handrews
force-pushed
the
style-examples-2
branch
from
68bfa30 to
da7b2fa
Compare
|
Between the ongoing debate over |
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.