json-schema_skill

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