JSON:API Specification: Format Guide & Implementation

JSON:API is a battle-tested specification for structuring JSON responses from REST APIs. It standardizes resource objects, relationships, links, filtering, sorting, and pagination so that clients and servers speak the same language without custom conventions.

Core Resource Object Structure

Every JSON:API response wraps resources in a top-level data key. Each resource has a type, id, attributes, and optionally relationships and links:

// GET /articles/1
// Content-Type: application/vnd.api+json

{
  "data": {
    "type": "articles",
    "id": "1",
    "attributes": {
      "title": "JSON:API Explained",
      "body": "JSON:API standardizes your REST responses...",
      "published-at": "2026-01-15T10:00:00Z"
    },
    "relationships": {
      "author": {
        "data": { "type": "people", "id": "9" }
      },
      "tags": {
        "data": [
          { "type": "tags", "id": "2" },
          { "type": "tags", "id": "7" }
        ]
      }
    },
    "links": {
      "self": "/articles/1"
    }
  }
}

Sideloading Related Resources (included)

Avoid N+1 requests by including related resources in the same response using the included array. Clients request this with the include query parameter:

// GET /articles/1?include=author,tags

{
  "data": {
    "type": "articles",
    "id": "1",
    "attributes": { "title": "JSON:API Explained" },
    "relationships": {
      "author": { "data": { "type": "people", "id": "9" } }
    }
  },
  "included": [
    {
      "type": "people",
      "id": "9",
      "attributes": { "name": "Vic Chen", "twitter": "@vicdev" }
    },
    {
      "type": "tags",
      "id": "2",
      "attributes": { "name": "api-design" }
    }
  ]
}

Filtering, Sorting & Sparse Fieldsets

JSON:API recommends standard query parameter patterns for common operations. Implementations define the exact filter syntax, but the parameter names are standardized:

# Filter articles by status
GET /articles?filter[status]=published

# Sort ascending by title, descending by published date
GET /articles?sort=title,-published-at

# Sparse fieldsets: only return title and body attributes
GET /articles?fields[articles]=title,body

# Combine: paginate + filter + include author
GET /articles?page[number]=2&page[size]=10&filter[status]=published&include=author

# Response includes pagination links
# {
#   "data": [...],
#   "links": {
#     "first": "/articles?page[number]=1&page[size]=10",
#     "prev": "/articles?page[number]=1&page[size]=10",
#     "next": "/articles?page[number]=3&page[size]=10",
#     "last": "/articles?page[number]=12&page[size]=10"
#   }
# }

JSON:API vs REST vs GraphQL