json-schema-design

# JSON Schema Design

Define precise data contracts with JSON Schema for validation, documentation, and code generation.

## Schema Fundamentals

### Basic Types

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://organvm.dev/schemas/repo.json",
  "title": "Repository",
  "description": "An ORGANVM repository entry",
  "type": "object",
  "required": ["name", "organ", "tier", "status"],
  "properties": {
    "name": {
      "type": "string",
      "pattern": "^[a-z][a-z0-9-]*$",
      "minLength": 2,
      "maxLength": 64
    },
    "organ": {
      "type": "string",
      "enum": ["I", "II", "III", "IV", "V", "VI", "VII", "META"]
    },
    "tier": {
      "type": "string",
      "enum": ["flagship", "standard", "infrastructure"]
    },
    "status": {
      "type": "string",
      "enum": ["LOCAL", "CANDIDATE", "PUBLIC_PROCESS", "GRADUATED", "ARCHIVED"]
    },
    "tags": {
      "type": "array",
      "items": { "type": "string" },
      "uniqueItems": true
    }
  },
  "additionalProperties": false
}
```

### Numeric Constraints

```json
{
  "priority": {
    "type": "integer",
    "minimum": 1,
    "maximum": 10
  },
  "score": {
    "type": "number",
    "exclusiveMinimum": 0,
    "maximum": 1.0
  }
}
```

## Composition

### $ref (Reuse)

```json
{
  "$defs": {
    "organ": {
      "type": "string",
      "enum": ["I", "II", "III", "IV", "V", "VI", "VII", "META"]
    },
    "timestamp": {
      "type": "string",
      "format": "date-time"
    }
  },
  "properties": {
    "source_organ": { "$ref": "#/$defs/organ" },
    "target_organ": { "$ref": "#/$defs/organ" },
    "created_at": { "$ref": "#/$defs/timestamp" }
  }
}
```

### allOf (Intersection / Extension)

```json
{
  "allOf": [
    { "$ref": "#/$defs/base-entity" },
    {
      "properties": {
        "extra_field": { "type": "string" }
      }
    }
  ]
}
```

### oneOf (Discriminated Union)

```json
{
  "oneOf": [
    {
      "properties": {
        "type": { "const": "skill" },
        "category": { "type": "string" }
      },
      "required": ["type", "category"]
    },
    {
      "properties": {
        "type": { "const": "bundle" },
        "includes": { "type": "array", "items": { "type": "string" } }
      },
      "required": ["type", "includes"]
    }
  ],
  "discriminator": { "propertyName": "type" }
}
```

### if/then/else (Conditional)

```json
{
  "if": {
    "properties": { "tier": { "const": "flagship" } }
  },
  "then": {
    "required": ["ci_url", "docs_url"]
  }
}
```

## Patterns for Common Needs

### Extensible Enums

```json
{
  "status": {
    "anyOf": [
      { "enum": ["active", "archived", "draft"] },
      { "type": "string", "pattern": "^x-" }
    ]
  }
}
```

### Maps / Dictionaries

```json
{
  "metadata": {
    "type": "object",
    "additionalProperties": { "type": "string" },
    "propertyNames": { "pattern": "^[a-z_]+$" }
  }
}
```

### Nullable Fields

```json
{
  "description": {
    "oneOf": [
      { "type": "string" },
      { "type": "null" }
    ]
  }
}
```

## Validation in Python

```python
import jsonschema
import json
from pathlib import Path

def validate_entry(data: dict, schema_path: str) -> list[str]:
    schema = json.loads(Path(schema_path).read_text())
    validator = jsonschema.Draft202012Validator(schema)
    errors = sorted(validator.iter_errors(data), key=lambda e: list(e.path))
    return [f"{'.'.join(str(p) for p in e.path)}: {e.message}" for e in errors]
```

## Schema Evolution

| Change | Safe? | Strategy |
|--------|-------|----------|
| Add optional field | Yes | No version bump needed |
| Add required field | No | Major version, provide default |
| Remove field | No | Deprecate first, then remove |
| Widen type (string → string\|number) | Yes | Backward compatible |
| Narrow type | No | Major version |
| Add enum value | Yes | Consumers should handle unknown |
| Remove enum value | No | Deprecate first |

## Anti-Patterns

- **No `additionalProperties: false`** — Typos in field names pass silently
- **Overly permissive types** — Use specific types and constraints
- **Inline definitions everywhere** — Extract to `$defs` for reuse
- **No `$id` or `$schema`** — Always specify schema version and identity
- **Validating only on write** — Validate on both read and write boundaries