Skip to main content
skill CX Codex

jsonapi — Claude Code skill: JSON:API rules, install

Checks API endpoints and responses against JSON:API v1.1. Use it when building, changing, or reviewing an API.

Apache-2.0 ★ 15,302 updated 2026-10-25

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add prowler-cloud/prowler --skill jsonapi -a claude-code
Open on GitHub

What jsonapi does

The skill applies JSON:API rules to document structure, resources, relationships, headers, errors, and status codes. It checks that data and errors are not returned together, resource id values are strings, type uses lowercase kebab-case, and foreign keys stay in relationships. Query handling covers page, filter, sort, fields, and include.

Before an endpoint is created or changed, the skill requires a check against the current specification. Context7 MCP is the preferred lookup path; WebFetch with https://jsonapi.org/format/ is the fallback. For Django REST Framework work, pair it with django-drf: this skill covers specification rules, while django-drf covers ViewSets, Serializers, and Filters. That distinction matters when a review must address both the response format and its implementation.

What it helps with

  • validate an API response against JSON:API rules
  • keep data and errors in separate responses
  • check string resource IDs and kebab-case types
  • move foreign keys out of attributes
  • verify status codes and query parameters

Example prompts for the agent

  • Check this endpoint against JSON:API v1.1 and list every violation.
  • Review the response with data, relationships, and errors, then suggest compliant changes.
  • Validate the handling of page, filter, sort, and include against the JSON:API rules.

How to install jsonapi

1Skills CLI (Vercel)

npx skills add prowler-cloud/prowler --skill jsonapi -a claude-code

2Manually: put the files in place

~/.claude/skills/jsonapi/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/jsonapi/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about jsonapi

How do I install jsonapi in Claude Code?

Run npx skills add prowler-cloud/prowler --skill jsonapi -a claude-code. Then check ~/.claude/skills/jsonapi/SKILL.md.

What does the jsonapi skill do?

It reviews API endpoints and responses against JSON:API v1.1, including document structure, resources, relationships, errors, headers, status codes, and query parameters.

Should jsonapi be used with django-drf?

Yes, when creating or changing endpoints. jsonapi checks specification requirements, while django-drf covers ViewSets, Serializers, and Filters.

Source text

SKILL.md · Apache-2.0
---
name: jsonapi
description: >
  Strict JSON:API v1.1 specification compliance.
  Trigger: When creating or modifying API endpoints, reviewing API responses, or validating JSON:API compliance.
license: Apache-2.0
metadata:
  author: prowler-cloud
  version: "1.0.0"
  scope: [root, api]
  auto_invoke:
    - "Creating API endpoints"
    - "Modifying API responses"
    - "Reviewing 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:

```text
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:

```text
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

© prowler-cloud · Apache-2.0 · prowler-cloud/prowler

Similar skills

SKILL.md skills catalog →

From the same set13

The whole set →
django-drf django-drf — a skill for building REST APIs on Django with ViewSets, serializers, and filters following Prowler standards. Use it when coding endpoints with RLS, JSON:API, and OpenAPI docs. CX Codex +1 484installs prowler-ci prowler-ci is a Claude Code skill that helps investigate GitHub Actions failures and PR validation gates in the Prowler repository. CX Codex +1 ★ 15,302repo stars prowler-changelog This skill manages Prowler changelog fragments for component changes and pull requests. It helps keep release notes in the required format. CX Codex +1 ★ 15,302repo stars prowler-docs prowler-docs sets the writing rules for Prowler documentation: brand voice, Title Case headings, MDX blocks, term handling. Useful when a tutorial or a release note has to match the project's style. CX Codex +1 ★ 15,302repo stars prowler-compliance-review prowler-compliance-review reviews pull requests adding or updating compliance frameworks in Prowler. Validates JSON schemas, detects duplicate IDs, and flags missing checks. CX Codex +1 ★ 15,302repo stars prowler-compliance Handles Prowler compliance frameworks end to end: authoring the JSON, syncing with the upstream catalog, and reviewing how checks map to requirements. CX Codex +1 ★ 15,302repo stars prowler-test-ui prowler-test-ui enforces Playwright E2E testing conventions for Prowler UI. Useful when building or editing tests inside ui/tests. CX Codex +1 ★ 15,302repo stars prowler-sdk-check prowler-sdk-check — a skill for Claude Code, Codex, Cursor and other AI IDEs that writes Prowler security checks following SDK patterns. CX Codex +1 ★ 15,302repo stars

Project sponsors

Companies that keep this analytics open