JSON Schema Best Practices

1. Define a Clear Purpose

Before writing any schema, clearly define what data it should validate and what rules apply. This helps in creating focused and effective schemas.

2. Use $id and $schema Keywords

Always include $id to uniquely identify your schema and $schema to specify the JSON Schema draft version you are using. This improves discoverability and ensures correct interpretation.

{
  "$id": "https://example.com/schemas/product.json",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Product",
  "description": "A product in the catalog"
}

3. Leverage Reusability with $ref

Avoid duplication by defining common patterns as separate schemas and referencing them using $ref. This makes your schemas modular and easier to maintain.

4. Provide Clear Descriptions and Examples

Use title, description, and examples to make your schemas self-documenting. This is crucial for developers who will use or extend your schemas.

5. Be Specific with Types and Formats

Always specify the type of data (e.g., string, number, object, array) and use format (e.g., email, date-time) for common data patterns.