К основному содержанию
скилл CX Codex

jsonapi — скилл для Claude Code: JSON:API и установка

Проверяет API-эндпоинты и ответы на соответствие JSON:API v1.1. Нужен при создании, изменении и ревью API.

Apache-2.0 ★ 15 302 обновлён 2026-10-25

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add prowler-cloud/prowler --skill jsonapi -a claude-code
Открыть на GitHub

Что делает jsonapi

Скилл задаёт правила для структуры JSON:API: разделяет data и errors, требует строковые id, kebab-case для type, корректные relationships и заголовки Content-Type и Accept. Он также помогает проверить коды ответов для GET, POST, PATCH и DELETE, ошибки и query-параметры page, filter, sort, fields и include.

Перед созданием или изменением endpoint нужно сверить актуальную спецификацию: предпочтительный способ — запросить её через Context7 MCP, запасной — использовать WebFetch для https://jsonapi.org/format/. Для реализации на Django REST Framework скилл советует подключать django-drf вместе с jsonapi, потому что первый отвечает за ViewSets, Serializers и Filters. Без этой пары проверка спецификации не заменяет шаблоны реализации в DRF.

Какие задачи решает

  • проверить ответ API на правила JSON:API
  • разделить data и errors в ответе
  • проверить строковые id и kebab-case для type
  • найти неверные связи и внешние ключи в attributes
  • сверить HTTP-коды и query-параметры

Примеры запросов агенту

  • Проверь этот endpoint на соответствие JSON:API v1.1 и укажи нарушения.
  • Проверь ответ с data, relationships и errors, затем предложи исправления.
  • Сверь обработку page, filter, sort и include с правилами JSON:API.

Как установить jsonapi

1Через Skills CLI (Vercel)

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

2Вручную: положить файлы

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

Папка скилла целиком; для одного проекта — .claude/skills/jsonapi/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о jsonapi

Как установить jsonapi в Claude Code?

Выполните npx skills add prowler-cloud/prowler --skill jsonapi -a claude-code. Затем проверьте файл ~/.claude/skills/jsonapi/SKILL.md.

Что делает скилл jsonapi?

Он проверяет API-эндпоинты и ответы по правилам JSON:API v1.1: структуру документов, ресурсы, связи, ошибки, заголовки и HTTP-коды.

Нужен ли django-drf вместе с jsonapi?

При создании или изменении endpoint да. jsonapi отвечает за требования спецификации, а django-drf — за паттерны ViewSets, Serializers и Filters.

Исходный текст

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

Похожие скиллы

Каталог скиллов SKILL.md →
find-skills vercel-labs Скилл find-skills для Claude Code ищет скиллы по задаче и помогает выбрать, что установить. Он включается, когда нужно найти готовую возможность для агента. CX Codex +1 4 400 000установок frontend-design официальный anthropics Скилл frontend-design для Claude Code задаёт осмысленное визуальное направление для новых интерфейсов и редизайна. Помогает уйти от шаблонного UI. CX Codex +1 1 025 790установок agent-browser vercel-labs Скилл agent-browser для Claude Code управляет браузером по запросам на навигацию, заполнение форм и проверку веб-приложений. Агент также может запускать через него исследовательское тестирование и автоматизировать Electron-приложения. CX Codex +1 1 600 000установок design-taste-frontend Leonxlnx Скилл design-taste-frontend для Claude Code задаёт правила оформления и проверки сайтов. Подключается при создании или переделке страницы, а также при просьбе убрать шаблонный вид. CX Codex +1 802 600установок grill-me Matt Pocock Скилл grill-me проводит жёсткое интервью по плану или дизайну, чтобы найти пробелы и уточнить решения. Подойдёт перед началом разработки. CX Codex +1 1 424 476установок grill-with-docs Matt Pocock Скилл grill-with-docs проводит жёсткое интервью по плану или дизайну и по ходу создаёт ADR и глоссарий. Подойдёт перед началом сложной разработки. CX Codex +1 1 219 756установок

Из того же набора13

Весь набор →
django-drf Скилл django-drf для быстрого создания REST API на Django с ViewSet'ами, сериализаторами и фильтрами по стандартам Prowler. Подключайте, когда пишете endpoints с RLS, JSON:API и OpenAPI документацией. CX Codex +1 484установок prowler-ci Скилл prowler-ci помогает разбираться с падениями проверок GitHub Actions и правилами пулл-реквестов в репозитории Prowler. CX Codex +1 ★ 15 302звёзд репо prowler-changelog Скилл prowler-changelog ведёт записи в CHANGELOG для компонентов Prowler через фрагменты changelog.d. Пригодится при подготовке PR и изменениях в UI, API, SDK или MCP Server. CX Codex +1 ★ 15 302звёзд репо prowler-docs Скилл prowler-docs для Claude Code задаёт стиль и структуру документации Prowler: голос бренда, Title Case, MDX-блоки и правила для терминов. Используется при написании гайдов и release notes. CX Codex +1 ★ 15 302звёзд репо prowler-compliance-review Скилл prowler-compliance-review проверяет пулреквесты с фреймворками комплаенса в репозитории Prowler. Находит синтаксические ошибки JSON, дубликаты ID и пропущенные проверки. CX Codex +1 ★ 15 302звёзд репо prowler-compliance Скилл prowler-compliance ведёт compliance-фреймворки Prowler от создания JSON до синхронизации с каталогом-первоисточником и ревизии привязки чеков к требованиям. CX Codex +1 ★ 15 302звёзд репо prowler-test-ui Скилл prowler-test-ui задаёт правила E2E-тестирования интерфейса Prowler на Playwright. Пригодится при написании и правке тестов в каталоге ui/tests. CX Codex +1 ★ 15 302звёзд репо prowler-sdk-check Скилл prowler-sdk-check для Claude Code, Codex, Cursor и других IDE помогает писать проверки безопасности Prowler по архитектурным паттернам SDK. CX Codex +1 ★ 15 302звёзд репо

Спонсоры проекта

Компании, которые помогают держать аналитику открытой