claude-mods/skills/cli-patterns/references/json-schemas.md

JSON Output Schemas

Complete JSON response patterns for CLI tools.

List Response (Paginated)

{
  "data": [
    {"id": "item-001", "name": "First Item", "status": "ACTIVE"},
    {"id": "item-002", "name": "Second Item", "status": "DRAFT"}
  ],
  "meta": {
    "count": 2,
    "total": 156,
    "page": 1,
    "per_page": 20,
    "has_more": true,
    "next_cursor": "eyJpZCI6Iml0ZW0tMDAyIn0="
  }
}

List Response (Simple)

For tools where pagination metadata isn't relevant:

{
  "data": [
    {"id": "1", "name": "Item 1"},
    {"id": "2", "name": "Item 2"}
  ]
}

Or minimal array form:

[
  {"id": "1", "name": "Item 1"},
  {"id": "2", "name": "Item 2"}
]

Single Item Response

{
  "data": {
    "id": "item-001",
    "name": "Example Item",
    "description": "A sample item",
    "status": "ACTIVE",
    "metadata": {
      "created_by": "user-123",
      "tags": ["important", "urgent"]
    },
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T14:22:00Z"
  }
}

Mutation Response

{
  "data": {
    "id": "item-003",
    "name": "New Item",
    "status": "DRAFT",
    "created_at": "2025-01-27T09:15:00Z"
  },
  "meta": {
    "action": "created"
  }
}

Field Conventions

Type	JSON Type	Format	Example
Identifiers	string	Any format	"id": "item_abc123"
Timestamps	string	ISO 8601 with timezone	"created_at": "2025-01-15T10:30:00Z"
Dates (no time)	string	ISO 8601 date	"due_date": "2025-02-15"
Money	number	Decimal, not cents	"total": 1250.50
Currency	string	ISO 4217 code	"currency": "USD"
Booleans	boolean	true/false	"is_active": true
Nulls	null	Explicit, not omitted	"deleted_at": null
Enums	string	UPPER_SNAKE_CASE	"status": "IN_PROGRESS"
Arrays	array	Even if empty	"tags": []
Nested objects	object	Embedded, not ID-only	"user": {"id": "...", "name": "..."}

Error Response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input provided",
    "details": {
      "field": "amount",
      "reason": "must be positive",
      "value": -50
    }
  }
}

The details object is optional and contains context-specific information.

Pagination in Response

{
  "data": [...],
  "meta": {
    "count": 20,
    "total": 156,
    "page": 1,
    "per_page": 20,
    "has_more": true,
    "next_cursor": "eyJpZCI6ImFiYzEyMyJ9"
  }
}