Skip to content

Deprecate relaxed variants of media types #1966

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
bkoelman merged 2 commits into from
Apr 10, 2026
Merged

Deprecate relaxed variants of media types #1966

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
bd14bdb
Deprecate the relaxed variants of JSON:API media type extensions, now…
bkoelman Apr 9, 2026
b7031fb
Revert removal of relaxed media type in tests to maintain code coverage
bkoelman Apr 10, 2026
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
32 changes: 6 additions & 26 deletions docs/ext/openapi/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# JSON:API Extension for OpenAPI

This extension facilitates using OpenAPI client generators targeting JSON:API documents.
This extension facilitates the use of OpenAPI client generators targeting JSON:API documents.

In JSON:API, a resource object contains the `type` member, which defines the structure of nested [attributes](https://jsonapi.org/format/#document-resource-object-attributes) and [relationships](https://jsonapi.org/format/#document-resource-object-relationships) objects.
While OpenAPI supports such constraints using `allOf` inheritance with a discriminator property for the `data` member,
Expand All @@ -11,30 +11,10 @@ This extension addresses that limitation by defining additional discriminator pr
## URI

This extension has the URI `https://www.jsonapi.net/ext/openapi`.
Because code generators often choke on the double quotes in `Accept` and `Content-Type` HTTP header values, a relaxed form is also permitted: `openapi`.

For example, the following `Content-Type` header:

```http
Content-Type: application/vnd.api+json; ext="https://www.jsonapi.net/ext/openapi"
```

is equivalent to:

```http
Content-Type: application/vnd.api+json; ext=openapi
```

To avoid the need for double quotes when multiple extensions are used, the following relaxed form can be used:

```http
Content-Type: application/vnd.api+json; ext=openapi; ext=atomic
```

> [!NOTE]
> The [base specification](https://jsonapi.org/format/#media-type-parameter-rules) *forbids* the use of multiple `ext` parameters
> and *requires* that each extension name must be a URI.
> This extension relaxes both constraints for practical reasons, to workaround bugs in client generators that produce broken code otherwise.
> [!CAUTION]
> Early preview versions of this specification also permitted using `openapi` instead of the URI to work around bugs in client generators.
> This is no longer supported and is not part of the final version.

## Namespace

Expand All @@ -55,7 +35,7 @@ in [attributes](https://jsonapi.org/format/#document-resource-object-attributes)

* `openapi:discriminator` - A string that MUST be identical to the `type` member in the containing [resource object](https://jsonapi.org/format/#document-resource-objects).

Here's how an article (i.e. a resource of type "articles") might appear in a document:
Here's how an article (a resource of type "articles") might appear in a document:

```json
{
Expand All @@ -81,7 +61,7 @@ Here's how an article (i.e. a resource of type "articles") might appear in a doc
In addition to the members allowed by the [Atomic Operations extension](https://jsonapi.org/ext/atomic/),
the following member MAY be included in elements of an `atomic:operations` array:

* `openapi:discriminator` - A free-format string to facilitate generation of client code.
* `openapi:discriminator` - A free-format string to facilitate the generation of client code.

For example:

Expand Down
Loading
Loading