JSON:API document envelope

Contract

Every JSON document the service sends or accepts is a JSON:API (jsonapi.org, v1.1) document: primary resources under a top-level data member, failures under a top-level errors array (never both in one document), extras under meta, resource objects of type + id + attributes + relationships, and the application/vnd.api+json media type. Apply when shaping request/response bodies for a resource-style HTTP service; not for RFC 9457 problem-details bodies (a separate convention) and not when consuming a format you don't control.

Rules

1. Top-level members. A document carries at least one of data, errors, meta — and

data and errors never coexist. Nothing else wraps them: no {"success": true} flag, no {"result": ...} or {"payload": ...} nesting, no collection-named top-level key.

1. data holds the primary resource(s). One resource object for a single-resource

document, an array of resource objects for a collection, null for an absent to-one target, [] for an empty collection. On a success document data is present, never silently omitted.

1. Resource-object shape. Exactly this frame:

json { "type": "articles", "id": "1", "attributes": { }, "relationships": { } }

• type — the collection name, a string.
• id — ALWAYS a JSON string, even when the underlying key is an integer.
• attributes — the record's own fields; type and id never appear inside it.
• relationships — one entry per connection to another resource.

1. Foreign keys become relationships. A reference to another record is never a bare

author_id-style attribute; it is a relationship whose data is a resource identifier:

json "relationships": { "author": { "data": { "type": "people", "id": "9" } } }

To-many linkage is an array of {type, id} identifiers; an empty to-one is "data": null; an empty to-many is "data": [].

1. Compound documents. When related records ride along, their full resource objects go in

the top-level included array, and the primary resources point at them through relationships by {type, id} — related records are never inlined inside attributes.

1. Errors. errors is a top-level ARRAY of error objects with members like status (the

HTTP code as a string), title (a short type-level summary), detail (occurrence-specific), and source. Never a single error object, never a bare message string, never beside data.

1. meta. Non-standard extras — page counts, request ids, timings — go under top-level

meta (or a resource-level meta), never as loose top-level fields like total or page.

1. Media type. Documents travel as Content-Type: application/vnd.api+json, and clients

ask for them with the same value in Accept. Plain application/json is not the convention.

Worked examples

Collection with a reference — the ad-hoc default, then the conforming document:

json
BEFORE
{ "articles": [ { "id": 1, "title": "Caching basics", "author_id": 9 } ], "total": 1 }

json
AFTER
{
  "data": [
    { "type": "articles", "id": "1",
      "attributes": { "title": "Caching basics" },
      "relationships": { "author": { "data": { "type": "people", "id": "9" } } } }
  ],
  "meta": { "total": 1 }
}

Compound document — related record inlined vs. placed in included:

json
BEFORE
{ "article": { "id": 1, "title": "Caching basics",
               "author": { "id": 9, "name": "R. Ortiz" } } }

json
AFTER
{
  "data": { "type": "articles", "id": "1",
            "attributes": { "title": "Caching basics" },
            "relationships": { "author": { "data": { "type": "people", "id": "9" } } } },
  "included": [
    { "type": "people", "id": "9", "attributes": { "name": "R. Ortiz" } }
  ]
}

Failure — ad-hoc flag vs. the errors array:

json
BEFORE
{ "success": false, "error": "Article not found" }

json
AFTER
{ "errors": [ { "status": "404", "title": "Not Found",
                "detail": "No article numbered 7 exists." } ] }

Creation request — flat fields vs. a typed resource object:

json
BEFORE
{ "title": "Caching basics", "author_id": 9 }

json
AFTER
{ "data": { "type": "articles",
            "attributes": { "title": "Caching basics" },
            "relationships": { "author": { "data": { "type": "people", "id": "9" } } } } }

Edge cases & exceptions

• Empty collection → "data": [], not null, not an omitted member, not an error.
• Absent to-one target → the relationship stays, with "data": null — not a

..._id: null attribute and not a missing key.

• Creation → the request document's resource object may omit id; the response document

supplies the authoritative string id.

• Integer database keys → serialized as strings anyway ("7", not 7).
• meta with data is fine; meta with errors is fine; data with errors never.
• Pagination → page links (first, prev, next, last) under top-level links;

counts under meta.

• A field literally named type or id → it cannot live in attributes (reserved);

rename it (e.g. kind) or nest it.

Do / Don't

• Do wrap primary resources in data. Don't emit a collection-named top-level key.
• Do keep the record's fields inside attributes. Don't flatten them onto the resource

object.

• Do link records under relationships with {type, id} identifiers. Don't ship *_id

attributes.

• Do carry full related records in included. Don't inline them inside attributes.
• Do report failures as an errors array. Don't return {"success": false} or mix errors

with data.

• Do serialize every id as a string. Don't leak integer ids.
• Do declare application/vnd.api+json. Don't default to application/json.

Common mistakes

• {"users": [...]} / {"items": [...]} — the collection-named wrapper instead of data.
• {"success": true, "data": ...} — a boolean status flag the envelope never uses.
• Numeric id values copied straight from the database.
• Foreign keys (customer_id, owner_id) left inside attributes.
• A related record nested whole inside the parent's attributes instead of included.
• One error object (or a bare string) instead of the errors array; errors returned beside

data.

• total / page / request_id floating at the top level instead of under meta.
• Content-Type: application/json on a conforming document.

Quick checklist

• Top level: only data / errors / meta (plus links, included); never data with

errors.

• Every resource object: string type, string id, fields in attributes.
• Every reference: a relationships entry with {type, id} linkage — no *_id attributes.
• Related records: full objects in included, pointed at by {type, id}.
• Failures: errors array of status/title/detail objects.
• Extras: under meta. Media type: application/vnd.api+json.