Skip to content

Fix: #110. Interoperability considerations instead of new parameter #121

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.

Sign up for GitHub

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: main
Choose a base branch
from
Open

Fix: #110. Interoperability considerations instead of new parameter #121

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
240f6b9
Fix: #119. Mention interoperability considerations in registration.
ioggstream Mar 5, 2025
a75bbd5
Fix: #110. Don't need new parameter.
ioggstream Mar 5, 2025
76c3820
Remove OAS 2.0 considerations.
ioggstream Mar 18, 2025
23e1da7
Non-entry documents
ioggstream Mar 18, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 21 additions & 0 deletions draft-ietf-httpapi-rest-api-mediatypes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -251,6 +251,27 @@ Interoperability requirements for media type
registrations are discussed in Section 4.6 of {{!MEDIATYPE=RFC6838}}
and in the Interoperability Considerations of the "+yaml" Structured Syntax Suffix.

## Media type of referenced resources

An OpenAPI Description can reference external resources
that are not OpenAPI Documents (e.g., JSON Schema documents).
Clients should be aware that
even if they request a specific media type for those resources
(e.g., `Accept: application/openapi+yaml; version=3.1`),
the server might only be able to provide a more generic media type.

For example, a server that publishes a JSON Schema file,
which can be referenced by both OpenAPI and JSON Schema documents,
might choose to use the more generic `application/yaml` media type
instead of managing multiple specific media types for the same resource.

## Resources not containing an OpenAPI Object

A server can publish an OpenAPI resource that
does not contain an "OpenAPI Object".
In this case, the `version` parameter is useful to identify
the specification version.
Comment on lines +270 to +273
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is talking about using the version parameter in the Content-Type header of a response, or a similar usage, correct? Should this be made more clear when initially discussing the parameter usage? What happens when a version paramter is used in this way with an OpenAPI Document (with an OpenAPI Object) where the openapi field disagrees with the version parameter? "Disagrees" here needs to be handled with the same concerns over compatibility and version matching that I just brought up in #124.

Copy link
Collaborator Author

@ioggstream ioggstream Mar 19, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

using the version parameter in the Content-Type header of a response

Yes, this is stated in the document introduction: can you please check if it's clear enough here?

What happens when a version paramter disagrees with the version [specified in the OpenAPI object]

I think prescribing a behavior may go beyond the scope of the media type registration,
since:

  • it is responsibility of the sender to ensure the correct value of the media type;
  • it is a choice of the client to decide the tolerance threshold according to its use case.

Maybe the above wording could fit the Interoperability considerations.

Agree to discuss this further in #124.


# Security Considerations {#sec}

Security requirements for media type
Expand Down
Loading