Skip to content

v3.2: Allow Parameter/Header "examples" field with "content" field #4648

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 our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 4 commits into
base: v3.2-dev
Choose a base branch
from

Conversation

handrews
Copy link
Member

@handrews handrews commented Jun 2, 2025

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
  • schema changes are needed for this pull request but not done yet
  • no schema changes are needed for this pull request

@handrews handrews added param serialization Issues related to parameter and/or header serialization media and encoding Issues regarding media type support and how to encode data (outside of query/path params) example obj/keywords Issues with the Example Object or exampel(s) keywords labels Jun 2, 2025
@handrews handrews changed the title v3.???: Allow Parameter/Header examples w/content v3.???: Allow Parameter/Header "examples" field with "content" field Jun 4, 2025
@handrews handrews changed the title v3.???: Allow Parameter/Header "examples" field with "content" field v3.2: Allow Parameter/Header "examples" field with "content" field Jun 9, 2025
@handrews handrews marked this pull request as ready for review June 9, 2025 19:26
@handrews handrews requested review from a team as code owners June 9, 2025 19:26
handrews and others added 4 commits June 13, 2025 11:39
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.
Co-authored-by: Karen Etheridge <[email protected]>
@handrews
Copy link
Member Author

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
example obj/keywords Issues with the Example Object or exampel(s) keywords media and encoding Issues regarding media type support and how to encode data (outside of query/path params) param serialization Issues related to parameter and/or header serialization
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants