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