jsonapi

Use With django-drf

This skill focuses on spec compliance. For implementation patterns (ViewSets, Serializers, Filters), use django-drf skill together with this one.

When creating/modifying endpoints, invoke BOTH skills.

---

Before Implementing/Reviewing

ALWAYS validate against the latest spec before creating or modifying endpoints:

Option 1: Context7 MCP (Preferred)

If Context7 MCP is available, query the JSON:API spec directly:

mcp_context7_resolve-library-id(query="jsonapi specification")
mcp_context7_query-docs(libraryId="<resolved-id>", query="[specific topic: relationships, errors, etc.]")

Option 2: WebFetch (Fallback)

If Context7 is not available, fetch from the official spec:

WebFetch(url="https://jsonapi.org/format/", prompt="Extract rules for [specific topic]")

This ensures compliance with the latest JSON:API version, even after spec updates.

---

Critical Rules (NEVER Break)

Document Structure

• NEVER include both data and errors in the same response
• ALWAYS include at least one of: data, errors, meta
• ALWAYS use type and id (string) in resource objects
• NEVER include id when creating resources (server generates it)

Content-Type

• ALWAYS use Content-Type: application/vnd.api+json
• ALWAYS use Accept: application/vnd.api+json
• NEVER add parameters to media type without ext/profile

Resource Objects

• ALWAYS use string for id (even if UUID)
• ALWAYS use lowercase kebab-case for type
• NEVER put id or type inside attributes
• NEVER include foreign keys in attributes - use relationships

Relationships

• ALWAYS include at least one of: links, data, or meta
• ALWAYS use resource linkage format: {"type": "...", "id": "..."}
• NEVER use raw IDs in relationships - always use linkage objects

Error Objects

• ALWAYS return errors as array: {"errors": [...]}
• ALWAYS include status as string (e.g., "400", not 400)
• ALWAYS include source.pointer for field-specific errors

---

HTTP Status Codes (Mandatory)

When to Use Each

---

Document Structure

Success Response (Single)

{
  "data": {
    "type": "providers",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "attributes": {
      "alias": "Production",
      "connected": true
    },
    "relationships": {
      "tenant": {
        "data": {"type": "tenants", "id": "..."}
      }
    },
    "links": {
      "self": "/api/v1/providers/550e8400-..."
    }
  },
  "links": {
    "self": "/api/v1/providers/550e8400-..."
  }
}

Success Response (List)

{
  "data": [
    {"type": "providers", "id": "...", "attributes": {...}},
    {"type": "providers", "id": "...", "attributes": {...}}
  ],
  "links": {
    "self": "/api/v1/providers?page[number]=1",
    "first": "/api/v1/providers?page[number]=1",
    "last": "/api/v1/providers?page[number]=5",
    "prev": null,
    "next": "/api/v1/providers?page[number]=2"
  },
  "meta": {
    "pagination": {"count": 100, "pages": 5}
  }
}

Error Response

{
  "errors": [
    {
      "status": "400",
      "code": "invalid",
      "title": "Invalid attribute",
      "detail": "UID must be 12 digits for AWS accounts",
      "source": {"pointer": "/data/attributes/uid"}
    }
  ]
}

---

Query Parameters

...