json-schema

mcclowes's avatarfrom mcclowes

Use when working with JSON Schema for validation, OpenAPI schemas, type definitions, and data structure specification

⭐1stars🔀0forks📁View on GitHub🕐Updated Dec 21, 2025
[API Helpers]

When & Why to Use This Skill

This Claude skill streamlines the creation, validation, and management of JSON Schemas and OpenAPI specifications. It empowers developers to define robust data structures, ensure strict data integrity through validation keywords, and maintain high-quality API documentation, ultimately reducing integration errors and improving type safety across software projects.

Use Cases

  • API Contract Design: Defining precise request and response schemas to ensure seamless communication between frontend and backend services.
  • OpenAPI 3.1 Documentation: Authoring and refining standardized API specifications using the latest JSON Schema 2020-12 features, including nullable types and sibling references.
  • Data Validation Logic: Implementing complex validation rules using keywords like pattern, multipleOf, and uniqueItems to maintain high data quality.
  • Modular Schema Architecture: Utilizing $defs and $ref to create reusable data components, reducing redundancy in large-scale system designs.
  • Type Definition Generation: Converting abstract data requirements into formal JSON Schema definitions that can be used for automated code generation and type checking.
namejson-schema
descriptionUse when working with JSON Schema for validation, OpenAPI schemas, type definitions, and data structure specification

JSON Schema

Quick Start

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["id", "email"],
  "properties": {
    "id": { "type": "string", "format": "uuid" },
    "email": { "type": "string", "format": "email" },
    "age": { "type": "integer", "minimum": 0, "maximum": 150 },
    "role": { "enum": ["admin", "user", "guest"] },
    "tags": { "type": "array", "items": { "type": "string" } }
  }
}

Type Keywords

Type Validation Keywords
string minLength, maxLength, pattern, format
number/integer minimum, maximum, exclusiveMinimum, multipleOf
array items, minItems, maxItems, uniqueItems
object properties, required, additionalProperties

Composition

{
  "allOf": [{ "$ref": "#/$defs/Base" }, { "properties": { "extra": {} } }],
  "oneOf": [{ "type": "string" }, { "type": "number" }],
  "anyOf": [{ "minimum": 0 }, { "maximum": 100 }],
  "not": { "type": "null" }
}

References

{
  "$defs": {
    "Address": {
      "type": "object",
      "properties": { "street": { "type": "string" } }
    }
  },
  "properties": {
    "billing": { "$ref": "#/$defs/Address" },
    "shipping": { "$ref": "#/$defs/Address" }
  }
}

Common Formats

date-time, date, time, email, uri, uuid, ipv4, ipv6, hostname

OpenAPI 3.1 Notes

  • OpenAPI 3.1 uses JSON Schema 2020-12
  • Use nullable via type: ["string", "null"]
  • example for single example, examples for multiple
  • $ref can have siblings in 3.1 (not in 3.0)