- Notifications
You must be signed in to change notification settings - Fork9.1k
v3.2: Explain Param/Header/Enc example serialization#4673
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to ourterms of service andprivacy statement. We’ll occasionally send you account related emails.
Already on GitHub?Sign in to your account
Conversation
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. |
Uh oh!
There was an error while loading.Please reload this page.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
I love this example!
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
@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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
Assuming theapplication/linkset PR gets accepted, this example is obsolete, but I can show a similar technique withSet-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 handleSet-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...
Uh oh!
There was an error while loading.Please reload this page.
The rules for this have not been clear, and are not always intuitive.This states and explains them directly and ensures that theStyle Examples table matches the rules.
These updates are about header usage in the Response Object.
Actually ensure each pattern is matched - in the previous waythe example was written, the uniqueItems was not sufficientas a link with the same rel but different URI would have satisfiedthe conditions.Also, the text says "includes" these rels, so there could be moreentries.
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 casesthat will be documented there in other PRs.
Between the ongoing debate over |
handrews commentedJul 18, 2025 • edited
Loading Uh oh!
There was an error while loading.Please reload this page.
edited
Uh oh!
There was an error while loading.Please reload this page.
Uh oh!
There was an error while loading.Please reload this page.
NOTE: This is another PR split out from PR#4647, and makessignificant 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.