JSON Schema Validate + Transform Skill

What This Skill Enables

Claude can validate JSON against JSON Schema with Ajv — compiling schemas, reporting failures by instancePath, and using Ajv options to coerce types, apply defaults, and remove unknown properties so data is validated and normalized in one pass. For work beyond validation, it uses companion tools: json-schema-to-typescript to generate TypeScript types from a schema, and scripted migrations that re-validate every document against the target schema.

Compatibility

Native

• Claude Code / Claude: native skill usage via SKILL.md.
• Codex/OpenAI workflows: compatible with Agent Skills-style SKILL.md content as reusable workflow instructions.

Manual Adaptation

• Gemini CLI: native skill usage via .gemini/skills/<skill-name>/SKILL.md or .agents/skills/<skill-name>/SKILL.md where supported.
• Cursor: use the generated .cursor/rules/*.mdc adapter for project rules.
• OpenClaw and similar agents: use the same skill content as a reusable prompt/workflow file when native skill import is unavailable.

Prerequisites

Required:

• Claude Pro subscription
• Code Interpreter feature enabled
• JSON data or schema file uploaded

What Claude handles:

• Installing validation libraries (Ajv, Zod)
• Schema compilation and validation
• Error reporting and debugging
• Data transformation and migration
• Type generation from schemas

How to Use This Skill

Validate JSON Against Schema

Prompt: "Validate this JSON data against the provided JSON Schema. Show me all validation errors."

Claude will:

1. Load schema and data
2. Compile schema
3. Run validation
4. Report all errors with paths
5. Suggest fixes

Generate TypeScript Types

Prompt: "Generate TypeScript interfaces from this JSON Schema."

Claude will:

1. Parse the JSON Schema
2. Generate TypeScript types
3. Include JSDoc comments
4. Export as .d.ts file

Transform Data Format

Prompt: "Transform this API response from format A to format B according to this mapping schema."

Claude will:

1. Analyze source and target schemas
2. Create transformation logic
3. Map fields
4. Validate output
5. Return transformed data

Schema Migration

Prompt: "Migrate these 100 JSON documents from schema v1 to schema v2. Show me the migration script and any issues."

Claude will:

1. Compare schema versions
2. Identify changes
3. Generate migration script
4. Process all documents
5. Report any migration failures

Common Workflows

API Payload Validation

"Create a validation script that:
1. Loads this OpenAPI spec
2. Extracts the POST /users request schema
3. Validates this payload against it
4. Returns detailed error messages for invalid fields
5. Suggests corrections"

Config File Validation

"Validate all JSON config files in the uploaded directory:
1. Check against config.schema.json
2. Report which files are invalid
3. For each error, show: file, path, expected type, actual value
4. Suggest fixes for common errors
5. Generate a validation report"

Data Normalization

"Normalize this messy JSON data:
1. Validate against the schema
2. Fix common issues (trim strings, coerce types)
3. Remove extra properties not in schema
4. Fill in default values for missing optional fields
5. Export clean, validated JSON"

Batch Transformation

"Transform all JSON files from old format to new:
1. Load transformation rules
2. For each file:
   - Parse and validate source
   - Apply transformations
   - Validate against target schema
   - Save to output/
3. Report success/failure stats"

Tips for Best Results

1. Provide Complete Schemas: Include all $ref dependencies or use inline definitions
2. Specify Validation Rules: Be clear about strictness (additional properties, coercion, etc.)
3. Error Reporting: Ask for detailed error paths: "Show me the JSON path for each error"
4. Examples: Provide sample valid and invalid data
5. Version Info: Specify JSON Schema draft version (draft-07, 2019-09, 2020-12)
6. Custom Formats: If using custom formats, define validation logic
7. Large Datasets: For many files, ask Claude to process in batches

Advanced Features

Schema Generation

• Generate schema from sample JSON
• Infer types and patterns
• Add validation rules
• Export as JSON Schema or TypeScript

Complex Validations

• Custom validation functions
• Conditional schemas (if/then/else)
• Dependencies between properties
• Pattern properties
• Recursive schemas

Data Transformation Patterns

• Field renaming and mapping
• Nested object flattening/nesting
• Array transformations
• Type coercion with validation
• Conditional transformations

Troubleshooting

Issue: Schema validation too strict Solution: Ask Claude to adjust: "Allow additional properties" or "Coerce types when possible"

Issue: $ref resolution errors Solution: Either inline all schemas or ensure all referenced files are uploaded

Issue: Type coercion not working as expected Solution: Be explicit: "Convert string numbers to integers" or "Parse ISO date strings to Date objects"

Issue: Large JSON files cause memory issues Solution: "Process this file in streaming mode" or "Validate in chunks of 1000 records"

Issue: Validation errors are cryptic Solution: Ask for better errors: "Explain each validation error in plain English with examples"

Issue: Migration breaks data Solution: "Validate each step of the migration" and "Keep backup of original values for rollback"

Learn More

• JSON Schema Specification - Official JSON Schema docs
• Ajv Documentation - The fastest JSON Schema validator
• Zod - TypeScript-first schema validation
• Understanding JSON Schema - Comprehensive guide
• JSON Schema Tools - Validators and generators

Features

• Strict validation with detailed error reporting and JSON path references
• Schema-aware migration between schema versions with change detection
• Format and $ref handling with custom schema loaders
• CLI-friendly usage with batch processing support
• TypeScript type generation from JSON schemas (json-schema-to-typescript)
• Custom validation functions and conditional schemas (if/then/else)
• Data transformation pipelines with type coercion and normalization
• Multiple JSON Schema draft support (draft-07, 2019-09, 2020-12)

Use Cases

• API payload validation against OpenAPI specifications
• Configuration file validation and migration between versions
• Data pipeline guards with schema enforcement
• TypeScript type generation from JSON schemas
• Data normalization and cleaning with schema validation
• Batch transformation of JSON documents between formats

• Source repositorygithub.com 2025-10-15
• Documentationajv.js.org
• Package (SHA-256 pinned)/downloads/skills/json-schema-validation-transformation.zip