playbooks

home / skills / beshkenadze / claude-skills-marketplace / json-schema

json-schema skill

/skills/document/json-schema

This skill generates and validates JSON Schema definitions to document APIs and enforce data structures.

npx playbooks add skill beshkenadze/claude-skills-marketplace --skill json-schema

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
2.4 KB
---
name: json-schema
description: Generate and validate JSON Schema definitions. Use when asked to create schemas, validate JSON structure, or document API payloads.
version: 1.0.0
---

# JSON Schema Generator

## Overview

Creates JSON Schema definitions for data validation and API documentation.

## Instructions

When generating JSON Schema:

1. **Analyze the data structure** or requirements
2. **Determine types** for each field (string, number, object, array, etc.)
3. **Add constraints**: required fields, patterns, min/max values
4. **Include descriptions** for documentation
5. **Set appropriate `$schema`** version (draft-07 recommended)

## Schema Components

### Basic Types
- `string` - Text values
- `number` / `integer` - Numeric values
- `boolean` - True/false
- `object` - Nested structures
- `array` - Lists of items
- `null` - Null values

### Common Constraints
- `required` - Mandatory fields
- `minLength` / `maxLength` - String length
- `minimum` / `maximum` - Number bounds
- `pattern` - Regex validation
- `enum` - Allowed values
- `format` - Semantic formats (email, uri, date-time)

## Examples

### Example: User Schema

**Input:**
"Create a schema for a user with name, email, age, and optional phone"

**Output:**
```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "User",
  "type": "object",
  "required": ["name", "email", "age"],
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "User's full name"
    },
    "email": {
      "type": "string",
      "format": "email",
      "description": "User's email address"
    },
    "age": {
      "type": "integer",
      "minimum": 0,
      "maximum": 150,
      "description": "User's age in years"
    },
    "phone": {
      "type": "string",
      "pattern": "^\\+?[1-9]\\d{1,14}$",
      "description": "Optional phone number in E.164 format"
    }
  },
  "additionalProperties": false
}
```

## Guidelines

### Do
- Always include `$schema` declaration
- Add descriptions for all properties
- Use `additionalProperties: false` for strict validation
- Prefer specific formats over loose patterns
- Use `required` array for mandatory fields

### Don't
- Use overly permissive types (avoid `{}` or `true`)
- Skip validation constraints on user input
- Mix draft versions in same schema
- Forget to handle nullable fields explicitly

Overview

This skill generates and validates JSON Schema definitions for data validation and API documentation. It produces clear, versioned schemas with types, constraints, and descriptions to make payloads self-documenting and machine-validated. Use it to create strict or flexible schemas for inputs, responses, and configuration objects.

How this skill works

I analyze the target data structure or requirements, map each field to the correct JSON Schema type, and add constraints like required, min/max, patterns, enums, and formats. I include a $schema declaration (draft-07 recommended), property descriptions, and optional settings such as additionalProperties to control extra fields. I can also validate example JSON against the generated schema and return errors or suggested fixes.

When to use it

  • Designing API request and response contracts for clear client-server expectations
  • Validating incoming JSON payloads in services, webhooks, or command-line tools
  • Documenting data models for SDKs, integration guides, or developer portals
  • Generating mock data or test fixtures that must match a contract
  • Converting informal field lists or examples into executable validation rules

Best practices

  • Always declare $schema and use a consistent draft version across artifacts
  • Add descriptive property descriptions to improve documentation and usability
  • Prefer specific constraints (format, pattern, min/max) over loose types
  • Use required to list mandatory fields and additionalProperties: false for strict validation
  • Handle nullable fields explicitly (e.g., type: ["null","string"]) and avoid broad types like true or {}

Example use cases

  • Create a user schema with name, email, age, and optional phone including formats and limits
  • Validate webhook payloads and return precise error messages for missing or malformed fields
  • Document a payment request object with currency enum, amount bounds, and timestamp format
  • Generate schemas for configuration files so CI catches invalid settings before deploy
  • Convert CSV column descriptions into JSON Schema for downstream API validation

FAQ

Which JSON Schema draft do you recommend?

I recommend draft-07 for broad compatibility, unless your platform requires a newer draft; avoid mixing drafts in the same project.

How should I represent nullable fields?

Explicitly include null in the type, for example: "type": ["null","string"] or use a separate "nullable" annotation if your tooling supports it.