JSON:API
Community specification maintained by the JSON:API project
JSON:API is a specification that defines a standard structure and set of conventions for building web APIs that exchange data in JSON, covering how resources, relationships, pagination, filtering, sorting, and errors should be represented…
Definition
JSON:API is a specification that defines a standard structure and set of conventions for building web APIs that exchange data in JSON, covering how resources, relationships, pagination, filtering, sorting, and errors should be represented consistently across implementations. It exists to reduce the amount of ad hoc decision-making and inconsistency that typically occurs when different teams design REST-style JSON APIs independently, without any shared reference format.
Overview
REST APIs that return JSON are extremely common, but the term 'REST' itself does not prescribe a specific response shape, leading different teams to invent their own conventions for representing resources, relationships between them, pagination, sorting, and error formats. JSON:API was created to fill that gap by defining a concrete, opinionated specification for how JSON responses and requests should be structured, so that client and server implementations built against the spec can interoperate predictably rather than requiring bespoke documentation for every API's quirks. Mechanically, JSON:API defines a specific document structure: top-level 'data,' 'included,' 'meta,' 'links,' and 'errors' members, with each resource object carrying a 'type,' 'id,' 'attributes,' and 'relationships' section that distinguishes an entity's own fields from its connections to other resources. It also standardizes query parameter conventions for including related resources, sparse fieldsets to request only specific fields, pagination, filtering, and sorting, and defines a consistent error object format so clients can handle failures uniformly across any JSON:API-compliant server. JSON:API differs from GraphQL by keeping the traditional REST request-response model with fixed endpoints per resource type rather than a single flexible query endpoint, trading some of GraphQL's client-driven query flexibility for simpler caching behavior and more conventional HTTP semantics. It differs from OpenAPI in that OpenAPI documents and describes whatever API shape a team chooses, while JSON:API prescribes the shape itself; the two can be used together, describing a JSON:API-compliant API with an OpenAPI document. In practice, JSON:API is used by teams that want a consistent contract across many resource endpoints without designing bespoke conventions for each one, particularly in ecosystems with libraries and frameworks that generate JSON:API-compliant responses and clients automatically, reducing the amount of custom serialization code needed on both the server and client sides. Certain web frameworks include built-in or plugin support for emitting JSON:API-formatted responses directly. Its main trade-off is verbosity and rigidity: JSON:API's structured envelope, with its type, id, attributes, and relationships breakdown, is more verbose than a simpler flat JSON object, and its conventions may feel like unnecessary ceremony for very small or simple APIs that don't need that level of standardization. Teams building highly custom or query-flexible APIs sometimes prefer GraphQL, while teams wanting minimal structure often skip specification-driven JSON altogether and define their own lightweight formats tailored narrowly to a specific application's own needs rather than adopting a broader, general-purpose convention meant to work consistently across many different domains, teams, and resource shapes over time.
Specification
- Defines a standard document structure for JSON API responses
- Separates resource attributes from relationships explicitly
- Standardizes pagination, filtering, sorting, and sparse fieldsets
- Defines a consistent error object format across compliant APIs
- Uses conventional REST-style endpoints rather than a single query endpoint
- Can be described alongside OpenAPI documentation
- Supported by libraries that auto-generate compliant clients and servers
Use Cases
Alternatives
Frequently Asked Questions
From the Blog
Working With JSON in Python
Python's json module converts between JSON text and Python objects with four core functions. Learn to parse, create, read, and write JSON with practical examples.
Read More ProgrammingJavaScript Objects and JSON Explained
JavaScript objects store data as key-value pairs, and JSON is a text format for exchanging that data. Learn how they relate, differ, and convert between each other.
Read More AI & TechnologyHow to Force Reliable JSON Output From a Language Model
Reliable JSON comes from constrained decoding where the provider supports it, a tool or schema definition where it does not, and a validate-and-repair loop behind both. This article compares the three approaches, shows where each fails, and gives the parsing defences you still need.
Read More ProgrammingPython File I/O: Reading and Writing Files
Almost every real Python program reads or writes files — logs, configs, CSVs, JSON, reports. This guide covers text files, CSV, JSON, binary files, and the modern pathlib approach, with best practices for safe file handling.
Read More