JSON:API Compliance

Use With django-drf

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

Skill	Focus
jsonapi	What the spec requires (MUST/MUST NOT rules)
django-drf	How to implement it in DRF (code patterns)

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)

Operation	Success	Async	Conflict	Not Found	Forbidden	Bad Request
GET	200	-	-	404	403	400
POST	201	202	409	404	403	400
PATCH	200	202	409	404	403	400
DELETE	200/204	202	-	404	403	-

When to Use Each

Code	Use When
200 OK	Successful GET, PATCH with response body, DELETE with response
201 Created	POST created resource (MUST include Location header)
202 Accepted	Async operation started (return task reference)
204 No Content	Successful DELETE, PATCH with no response body
400 Bad Request	Invalid query params, malformed request, unknown fields
403 Forbidden	Authentication ok but no permission, client-generated ID rejected
404 Not Found	Resource doesn't exist OR RLS hides it (never reveal which)
409 Conflict	Duplicate ID, type mismatch, relationship conflict
415 Unsupported	Wrong Content-Type header

---

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

Family	Format	Example
page	page[number], page[size]	?page[number]=2&page[size]=25
filter	filter[field], filter[field__op]	?filter[status]=FAIL
sort	Comma-separated, - for desc	?sort=-inserted_at,name
fields	fields[type]	?fields[providers]=id,alias
include	Comma-separated paths	?include=provider,scan.task

Rules

• MUST return 400 for unsupported query parameters
• MUST return 400 for unsupported include paths
• MUST return 400 for unsupported sort fields
• MUST NOT include extra fields when fields[type] is specified

---

Common Violations (AVOID)

Violation	Wrong	Correct
ID as integer	"id": 123	"id": "123"
Type as camelCase	"type": "providerGroup"	"type": "provider-groups"
FK in attributes	"tenant_id": "..."	"relationships": {"tenant": {...}}
Errors not array	{"error": "..."}	{"errors": [{"detail": "..."}]}
Status as number	"status": 400	"status": "400"
Data + errors	{"data": ..., "errors": ...}	Only one or the other
Missing pointer	{"detail": "Invalid"}	{"detail": "...", "source": {"pointer": "..."}}

---

Relationship Updates

To-One Relationship

PATCH /api/v1/providers/123/relationships/tenant
Content-Type: application/vnd.api+json

{"data": {"type": "tenants", "id": "456"}}

To clear: {"data": null}

To-Many Relationship

Operation	Method	Body
Replace all	PATCH	{"data": [{...}, {...}]}
Add members	POST	{"data": [{...}]}
Remove members	DELETE	{"data": [{...}]}

---

Compound Documents (include)

When using ?include=provider:

{
  "data": {
    "type": "scans",
    "id": "...",
    "relationships": {
      "provider": {
        "data": {"type": "providers", "id": "prov-123"}
      }
    }
  },
  "included": [
    {
      "type": "providers",
      "id": "prov-123",
      "attributes": {"alias": "Production"}
    }
  ]
}

Rules

• Every included resource MUST be reachable via relationship chain from primary data
• MUST NOT include orphan resources
• MUST NOT duplicate resources (same type+id)

---

Spec Reference

• Full Specification: https://jsonapi.org/format/
• Implementation: Use django-drf skill for DRF-specific patterns
• Testing: Use prowler-test-api skill for test patterns