JSON Schema 完全指南

什么是 JSON Schema？

JSON Schema 是一种声明性语言，用于验证 JSON 数据的结构。它就像一个合约，定义了你的 JSON 应该是什么样子。

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "用户",
  "description": "系统中的用户",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "age": {
      "type": "integer",
      "minimum": 0,
      "maximum": 150
    },
    "email": {
      "type": "string",
      "format": "email"
    }
  },
  "required": ["name", "age"],
  "additionalProperties": false
}

基本类型

字符串

{
  "type": "string",
  "minLength": 1,
  "maxLength": 255,
  "pattern": "^[A-Za-z]+$"
}

格式：email、uri、date、date-time、time、ipv4、ipv6、uuid

数字

{
  "type": "number",
  "minimum": 0,
  "maximum": 100,
  "multipleOf": 0.01
}

数组

{
  "type": "array",
  "items": { "type": "string" },
  "minItems": 1,
  "maxItems": 10,
  "uniqueItems": true
}

对象

{
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "age": { "type": "integer" }
  },
  "required": ["name"],
  "additionalProperties": false
}

组合

allOf（与）

{
  "allOf": [
    { "type": "object", "properties": { "name": { "type": "string" } } },
    { "type": "object", "properties": { "age": { "type": "integer" } } }
  ]
}

anyOf（或）

{
  "anyOf": [
    { "type": "string" },
    { "type": "integer" }
  ]
}

oneOf（异或）

{
  "oneOf": [
    { "required": ["email"] },
    { "required": ["phone"] }
  ]
}

$ref（复用）

{
  "$defs": {
    "address": {
      "type": "object",
      "properties": {
        "street": { "type": "string" },
        "city": { "type": "string" }
      }
    }
  },
  "type": "object",
  "properties": {
    "home": { "$ref": "#/$defs/address" },
    "work": { "$ref": "#/$defs/address" }
  }
}

条件验证

{
  "type": "object",
  "properties": {
    "country": { "type": "string" },
    "postalCode": { "type": "string" }
  },
  "if": {
    "required": ["country"],
    "properties": { "country": { "const": "US" } }
  },
  "then": {
    "properties": {
      "postalCode": { "pattern": "^[0-9]{5}(-[0-9]{4})?$" }
    }
  },
  "else": {
    "properties": {
      "postalCode": { "minLength": 3 }
    }
  }
}

实际示例

API 请求验证

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "username": {
      "type": "string",
      "minLength": 3,
      "maxLength": 20,
      "pattern": "^[a-zA-Z0-9_]+$"
    },
    "password": {
      "type": "string",
      "minLength": 8,
      "pattern": "^(?=.*[a-z])(?=.*[A-Z])(?=.*\\d).*$"
    },
    "email": {
      "type": "string",
      "format": "email"
    },
    "roles": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": ["admin", "user", "moderator"]
      },
      "uniqueItems": true
    }
  },
  "required": ["username", "password", "email"],
  "additionalProperties": false
}

配置文件

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "database": {
      "type": "object",
      "properties": {
        "host": { "type": "string" },
        "port": { "type": "integer", "default": 5432 },
        "name": { "type": "string" }
      },
      "required": ["host", "name"]
    },
    "logging": {
      "type": "object",
      "properties": {
        "level": {
          "type": "string",
          "enum": ["debug", "info", "warn", "error"]
        },
        "file": { "type": "string" }
      }
    }
  },
  "required": ["database"]
}

工具

验证库

代码生成

# 从 JSON Schema 生成 TypeScript
npx json-schema-to-typescript schema.json > types.ts

# 从 JSON Schema 生成 Python
datamodel-codegen --input schema.json --output models.py

最佳实践

1. 从简单开始 — 按需添加约束
2. 使用 $ref — 不要重复自己
3. 版本化 schema — 在 $id 中包含版本
4. 充分测试 — 使用有效和无效测试用例
5. 文档化格式 — 自定义格式需要自定义验证器

相关资源

• JSON Schema 验证器 — 验证你的 JSON
• JSON 格式化工具 — 格式化 JSON
• JSON Diff 工具 — 比较 JSON 结构
• JSON 最佳实践 — 通用最佳实践
• JSON 安全 — 安全防护