Skip to content

Fix: #125. Support OAS 2.0. #126

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

Merged
ioggstream merged 3 commits into from
Dec 11, 2025
Merged

Fix: #125. Support OAS 2.0. #126

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
1dbd3ea
Fix: #125. Support OAS 2.0.
ioggstream Sep 15, 2025
194cae2
Use generic terms. Delegate terminology to OAS.
ioggstream Dec 9, 2025
fffefe6
Apply suggestions from code review
ioggstream Dec 11, 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
27 changes: 19 additions & 8 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 @@ -76,13 +76,13 @@ and application/openapi+yaml.

# Introduction

OpenAPI Specification [OAS] version 3 and above
OpenAPI Specification [OAS]
is a consolidated standard for describing
HTTP APIs using the JSON {{JSON}} and YAML [YAML] data format.

To increase interoperability when processing API descriptions
To increase interoperability
and leverage content negotiation mechanisms when exchanging
OpenAPI description representations
API descriptions
this specification registers the following media types:
`application/openapi+json`
and `application/openapi+yaml`.
Expand All @@ -97,20 +97,20 @@ in this document are to be interpreted as in {{HTTP}}.

# Media Type registrations

This section describes the information required to register
the above media types according to {{MEDIATYPE}}.
This section describes the information required for IANA to register
the above media types per {{MEDIATYPE}}.

## The OpenAPI Media Types

The OpenAPI Specification Media Types convey semantics for OpenAPI Document (OAD) resources
as defined in [OAS] for version 3.0 and above.
The OpenAPI Specification Media Types convey semantics for OpenAPI resources
as defined in [OAS].

Those resources can be represented in {{JSON}} or [YAML].
Since there are multiple OpenAPI Specification versions,
those media types support the `version` parameter.

The following example conveys the desire of a client
to receive an OpenAPI Document resource based on the stated
to receive an OpenAPI Specification resource based on the stated
preferences:

1. openapi 3.1 in YAML
Expand Down Expand Up @@ -266,6 +266,11 @@ its value is expected to be ignored
by tooling
(see https://spec.openapis.org/oas/v3.1.0.html#versions).

While it is possible to use the version parameter
to identify OpenAPI resources prior to version 3.0,
the terminology used in this document
was formally introduced in OAS 3.0.4 and OAS 3.1.1.

# Security Considerations {#sec}

Security requirements for media type
Expand Down Expand Up @@ -349,3 +354,9 @@ RFC EDITOR PLEASE DELETE THIS SECTION.
{:numbered="false" removeinrfc="true"}

- Split JSONSCHEMA registrations in a separate I-D.

## Since -07
{:numbered="false" removeinrfc="true"}

- Support OAS 2.0

Loading