JSON:API is a specification for how a client should request and modify resources, and how a server should respond, using JSON. It standardises document structure, pagination, filtering, sparse fieldsets and relationships so clients and servers can interoperate without bespoke conventions.

What must a top-level JSON:API document contain?

A document MUST contain at least one of data, errors or meta. The members data and errors MUST NOT coexist in the same document. data holds the primary resource(s); errors holds an array of error objects.

What is a resource object?

A resource object identifies and describes a single resource. It MUST contain a type and, except when newly created client-side, an id. It MAY also carry attributes, relationships, links and meta. The combination of type and id uniquely identifies a resource.

What goes in the relationships member?

relationships describes links between resources. Each relationship may include links (self and related), resource linkage data (resource identifier objects with type and id), and meta. To-one relationships use a single object or null; to-many use an array.

Does the tool send my data anywhere?

No. This is a static reference rendered and searched entirely in your browser. Nothing is uploaded.

JSON:API Spec Reference

Email me this result

Get this tool's output sent to your inbox, plus one useful tool a week. No spam, unsubscribe any time.

The JSON:API v1.1 document structure

JSON:API standardises the shape of request and response bodies: where the primary data lives, how errors are returned, how resources link to one another, and which members are allowed at each level. This reference covers the top-level document, resource objects, relationships, links and error objects.

How it works

Every JSON:API response is a single document. At the top level it carries data, errors or meta (at least one, and data/errors are mutually exclusive):

{
  "data": {
    "type": "articles",
    "id": "1",
    "attributes": { "title": "JSON:API" },
    "relationships": {
      "author": {
        "links": { "self": "/articles/1/relationships/author" },
        "data": { "type": "people", "id": "9" }
      }
    },
    "links": { "self": "/articles/1" }
  }
}

A resource object is identified by its type plus id. Relationships hold resource linkage (resource identifier objects) and links. Error objects appear in an errors array, each describing one problem with members like status, code, title, detail and source.

Tips and notes

data and errors MUST NOT both appear in one document.
A client-created resource MAY omit id; the server assigns it.
Use the included array for compound documents (related resources inline).
Error source.pointer is a JSON Pointer to the offending member.