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.

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)

json

{
  "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)

json

{
  "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

json

{
  "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

http

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

json

{
  "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

jsonapi

NPX Install

Tags

SKILL.md Content

Use With django-drf

Before Implementing/Reviewing

Option 1: Context7 MCP (Preferred)

Option 2: WebFetch (Fallback)

Critical Rules (NEVER Break)

Document Structure

Content-Type

Resource Objects

Relationships

Error Objects

HTTP Status Codes (Mandatory)

When to Use Each

Document Structure

Success Response (Single)

Success Response (List)

Error Response

Query Parameters

Rules

Common Violations (AVOID)

Relationship Updates

To-One Relationship

To-Many Relationship

Compound Documents (
`include`
)

Rules

Spec Reference

jsonapi

NPX Install

Tags

SKILL.md Content

Use With django-drf

Before Implementing/Reviewing

Option 1: Context7 MCP (Preferred)

Option 2: WebFetch (Fallback)

Critical Rules (NEVER Break)

Document Structure

Content-Type

Resource Objects

Relationships

Error Objects

HTTP Status Codes (Mandatory)

When to Use Each

Document Structure

Success Response (Single)

Success Response (List)

Error Response

Query Parameters

Rules

Common Violations (AVOID)

Relationship Updates

To-One Relationship

To-Many Relationship

Compound Documents (include)

Rules

Spec Reference

Compound Documents (
`include`
)