Extensions and Profiles

The JSON:API specification provides a way to define new functionality not provided by the base specification using extensions. Additionally, it provides a means to share a particular usage of the specification among implementations using profiles.

Generally speaking, extensions provide a means to standardize a functionality that is not so widely needed that it should be part of the base specification but is general enough that it would benefit the community to have a standard. Typically, that functionality is also too difficult and/or unconventional to implement using only the parts of the specification that are reserved for implementations (e.g. implementations can add their own members to attributes objects, but can’t add new members to a resource identifier).

Profiles, on the other hand, are a way to standardize common usages of the base specification that are simple to implement using only the parts of the specification that are reserved for implementations (e.g. a common way to handle pagination).

One major difference between extensions and profiles is that an extension must be agreed upon and understood by both the client and the server, while a profile can be safely ignored if either the client or the server does not recognize it.

Some useful extensions and profiles are listed below. However, an extension or profile does not need to appear below to be valid. Anyone can author and host an extension or profile document using their own domain for its URI.

In order to keep the promise of JSON:API as an anti-bikeshedding tool, implementors are strongly encouraged to reuse, improve, and collaborate on common extensions and profiles instead of creating new extensions and profiles because of trivial or aesthetic differences.

The extensions and profiles listed on this page have been reviewed by the JSON:API specification editors and are considered:

• Compatible with the base specification
• Able to evolve without backward incompatibilities
• Broadly useful

Not every extension or profile can or should appear on this page. This listing is maintained on a best-effort basis.

Extensions

• Atomic Operations
  • URI: https://jsonapi.org/ext/atomic
  • Namespace: atomic
  • Description: This extension provides a means to perform multiple “operations” in a linear and atomic manner.

Profiles

• Cursor Pagination
  • URI: https://jsonapi.org/profiles/ethanresnick/cursor-pagination
  • Description: Cursor-based pagination (aka keyset pagination) is a common pagination strategy that avoids many of the pitfalls of “offset–limit” pagination.