How is a JSON:API document (media type application/vnd.api+json) laid out - what goes in data, relationships and included - and what does that structure buy you over ad-hoc JSON?

## Document skeleton Every JSON:API document is an object with at least one of: - **data** - the primary data: a resource object, an array of them, or null - **errors** - an array of error objects; data and errors must never both appear - **meta** - non-standard information and optionally **included**, **links**, and **jsonapi** (version info). ## Resource objects A resource object is identified by the pair **type** and **id** - the type is part of identity, not just a hint. Its own state lives under **attributes**; anything referencing another resource lives under **relationships**; **links** typically carries self. Crucially, attributes and relationships are separate namespaces, and foreign keys do not appear as attributes. authorId is not an attribute; the author relationship is where that edge is expressed. ## Relationships and identifier objects A relationship object may contain: - **data** - one or more **resource identifier objects**, which are the minimal type-and-id pairs - **links.self** - the relationship itself, which you can PATCH to change the linkage without touching the resource - **links.related** - where to fetch the related resource - **meta** That identifier-object indirection is what makes the format a graph rather than a tree. ## Compound documents and included When the client asks for related data with an include parameter, the server puts the full resources into the top-level **included** array. Each resource appears exactly once, keyed by its type and id, no matter how many relationships point at it. Clients typically index included by type and id on receipt and resolve pointers locally. This is the format's biggest practical win: a page of fifty articles by three authors carries three author objects, not fifty copies. ## The conventions that come free - **Sparse fieldsets**: fields[articles]=title,body limits which attributes are serialised, per type. - **include**: dot paths such as comments.author walk more than one hop. - **sort**, **page**, **filter**: sorting and pagination are specified; filter is deliberately left as a reserved, unspecified strategy. - **Errors**: an errors array whose members have id, status, code, title, detail, and source - where source.pointer is a JSON Pointer into the request document and source.parameter names a query parameter. Content negotiation is strict: the media type is application/vnd.api+json and the spec dictates responding 415 when a client sends it with media type parameters the server does not support, and 406 when it appears in Accept only with unsupported parameters. ## What it buys, and what it costs Buys: one convention instead of ten bikeshed decisions per team; deduplication for graph-shaped data; off-the-shelf client libraries that give you an identity map and a store almost for free; a uniform error shape; a linkage-editing mechanism via relationship endpoints. Costs: verbosity - a two-field object becomes a nested structure with type, id and attributes; a steep fit problem for anything that is not a persistent entity, such as a calculation endpoint or a workflow command; more serializer machinery; and enough rigidity that teams end up bending the spec, at which point the client-library advantage evaporates. ## How to choose it JSON:API pays off when the domain is genuinely a graph of entities that clients traverse and cache, and when several clients would otherwise each invent their own include and paging syntax. It is a poor fit for RPC-ish or document-shaped APIs, where its ceremony buys nothing.