1
0
Source

Strict JSON:API v1.1 specification compliance. Trigger: When creating or modifying API endpoints, reviewing API responses, or validating JSON:API compliance.

Install

mkdir -p .claude/skills/jsonapi && curl -L -o skill.zip "https://mcp.directory/api/skills/download/4037" && unzip -o skill.zip -d .claude/skills/jsonapi && rm skill.zip

Installs to .claude/skills/jsonapi

About this skill

Use With django-drf

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

SkillFocus
jsonapiWhat the spec requires (MUST/MUST NOT rules)
django-drfHow 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)

OperationSuccessAsyncConflictNot FoundForbiddenBad Request
GET200--404403400
POST201202409404403400
PATCH200202409404403400
DELETE200/204202-404403-

When to Use Each

CodeUse When
200 OKSuccessful GET, PATCH with response body, DELETE with response
201 CreatedPOST created resource (MUST include Location header)
202 AcceptedAsync operation started (return task reference)
204 No ContentSuccessful DELETE, PATCH with no response body
400 Bad RequestInvalid query params, malformed request, unknown fields
403 ForbiddenAuthentication ok but no permission, client-generated ID rejected
404 Not FoundResource doesn't exist OR RLS hides it (never reveal which)
409 ConflictDuplicate ID, type mismatch, relationship conflict
415 UnsupportedWrong 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

FamilyFormatExample
pagepage[number], page[size]?page[number]=2&page[size]=25
filterfilter[field], filter[field__op]?filter[status]=FAIL
sortComma-separated, - for desc?sort=-inserted_at,name
fieldsfields[type]?fields[providers]=id,alias
includeComma-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)

ViolationWrongCorrect
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

OperationMethodBody
Replace allPATCH{"data": [{...}, {...}]}
Add membersPOST{"data": [{...}]}
Remove membersDELETE{"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

You might also like

flutter-development

aj-geddes

Build beautiful cross-platform mobile apps with Flutter and Dart. Covers widgets, state management with Provider/BLoC, navigation, API integration, and material design.

228766

drawio-diagrams-enhanced

jgtolentino

Create professional draw.io (diagrams.net) diagrams in XML format (.drawio files) with integrated PMP/PMBOK methodologies, extensive visual asset libraries, and industry-standard professional templates. Use this skill when users ask to create flowcharts, swimlane diagrams, cross-functional flowcharts, org charts, network diagrams, UML diagrams, BPMN, project management diagrams (WBS, Gantt, PERT, RACI), risk matrices, stakeholder maps, or any other visual diagram in draw.io format. This skill includes access to custom shape libraries for icons, clipart, and professional symbols.

181403

godot

bfollington

This skill should be used when working on Godot Engine projects. It provides specialized knowledge of Godot's file formats (.gd, .tscn, .tres), architecture patterns (component-based, signal-driven, resource-based), common pitfalls, validation tools, code templates, and CLI workflows. The `godot` command is available for running the game, validating scripts, importing resources, and exporting builds. Use this skill for tasks involving Godot game development, debugging scene/resource files, implementing game systems, or creating new Godot components.

161268

nano-banana-pro

garg-aayush

Generate and edit images using Google's Nano Banana Pro (Gemini 3 Pro Image) API. Use when the user asks to generate, create, edit, modify, change, alter, or update images. Also use when user references an existing image file and asks to modify it in any way (e.g., "modify this image", "change the background", "replace X with Y"). Supports both text-to-image generation and image-to-image editing with configurable resolution (1K default, 2K, or 4K for high resolution). DO NOT read the image file first - use this skill directly with the --input-image parameter.

194225

ui-ux-pro-max

nextlevelbuilder

"UI/UX design intelligence. 50 styles, 21 palettes, 50 font pairings, 20 charts, 8 stacks (React, Next.js, Vue, Svelte, SwiftUI, React Native, Flutter, Tailwind). Actions: plan, build, create, design, implement, review, fix, improve, optimize, enhance, refactor, check UI/UX code. Projects: website, landing page, dashboard, admin panel, e-commerce, SaaS, portfolio, blog, mobile app, .html, .tsx, .vue, .svelte. Elements: button, modal, navbar, sidebar, card, table, form, chart. Styles: glassmorphism, claymorphism, minimalism, brutalism, neumorphism, bento grid, dark mode, responsive, skeuomorphism, flat design. Topics: color palette, accessibility, animation, layout, typography, font pairing, spacing, hover, shadow, gradient."

154187

fastapi-templates

wshobson

Create production-ready FastAPI projects with async patterns, dependency injection, and comprehensive error handling. Use when building new FastAPI applications or setting up backend API projects.

127166

Stay ahead of the MCP ecosystem

Get weekly updates on new skills and servers.