JSON Schema 入门与使用指南

作者：本站站长
发布日期：2026年3月17日

JSON Schema 是一种用于描述 JSON 数据结构的声明式语言。它就像 JSON 的"身份证"，可以验证数据是否符合预期的格式、类型和约束。本文将带你从零开始学习 JSON Schema 的核心概念和实际应用。

一、什么是 JSON Schema？

JSON Schema 本身也是一个 JSON 文档，用于定义其他 JSON 文档的结构。它可以：

• 验证数据类型（字符串、数字、布尔值等）
• 设置必填字段
• 定义数值范围
• 限制字符串长度和格式
• 指定数组元素类型和数量
• 定义嵌套对象结构

二、基础语法示例

1. 简单对象验证

假设我们有一个用户信息的 JSON：

{
  "name": "张三",
  "age": 25,
  "email": "zhangsan@example.com"
}

对应的 Schema：

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "用户姓名"
    },
    "age": {
      "type": "integer",
      "minimum": 0,
      "maximum": 150,
      "description": "用户年龄"
    },
    "email": {
      "type": "string",
      "format": "email",
      "description": "用户邮箱"
    }
  },
  "required": ["name", "email"]
}

三、常用关键字详解

1. type - 数据类型

指定字段的数据类型，可选值：

• "string" - 字符串
• "number" - 数字（整数或小数）
• "integer" - 整数
• "boolean" - 布尔值
• "object" - 对象
• "array" - 数组
• "null" - 空值

2. required - 必填字段

指定哪些字段必须存在：

{
  "type": "object",
  "properties": {
    "id": { "type": "string" },
    "name": { "type": "string" },
    "optional": { "type": "string" }
  },
  "required": ["id", "name"]  // id 和 name 必须存在
}

3. 字符串约束

{
  "username": {
    "type": "string",
    "minLength": 3,      // 最小长度
    "maxLength": 20,     // 最大长度
    "pattern": "^[a-zA-Z0-9_]+$"  // 正则表达式
  },
  "url": {
    "type": "string",
    "format": "uri"      // 预定义格式：email, uri, date-time 等
  }
}

4. 数值约束

{
  "price": {
    "type": "number",
    "minimum": 0,       // 最小值
    "maximum": 10000,    // 最大值
    "exclusiveMinimum": true  // 不包含最小值（大于0）
  },
  "quantity": {
    "type": "integer",
    "multipleOf": 1     // 必须是1的倍数
  }
}

5. 数组约束

{
  "tags": {
    "type": "array",
    "items": {
      "type": "string"
    },
    "minItems": 1,       // 最少元素数量
    "maxItems": 5,       // 最多元素数量
    "uniqueItems": true  // 元素必须唯一
  }
}

6. 嵌套对象

{
  "address": {
    "type": "object",
    "properties": {
      "province": { "type": "string" },
      "city": { "type": "string" },
      "street": { "type": "string" }
    },
    "required": ["province", "city"]
  }
}

四、高级特性

1. 枚举值（enum）

限制字段只能是特定的几个值之一：

{
  "status": {
    "type": "string",
    "enum": ["pending", "active", "completed", "cancelled"]
  }
}

2. 默认值（default）

{
  "role": {
    "type": "string",
    "default": "user"
  }
}

3. 条件验证（if/then/else）

{
  "type": "object",
  "properties": {
    "country": { "type": "string" },
    "postalCode": { "type": "string" }
  },
  "if": {
    "properties": {
      "country": { "const": "US" }
    }
  },
  "then": {
    "properties": {
      "postalCode": { "pattern": "^\\d{5}(-\\d{4})?$" }
    }
  }
}

4. 组合关键字（allOf/anyOf/oneOf）

{
  "allOf": [    // 必须满足所有条件
    { "type": "object" },
    { "required": ["id"] }
  ],
  "anyOf": [    // 满足任意一个条件即可
    { "required": ["email"] },
    { "required": ["phone"] }
  ],
  "oneOf": [    // 只能满足其中一个条件
    { "properties": { "type": { "const": "user" } } },
    { "properties": { "type": { "const": "admin" } } }
  ]
}

五、实际应用场景

1. API 接口验证

在接收客户端数据时进行验证：

// JavaScript 示例
const Ajv = require('ajv');
const ajv = new Ajv();

const schema = {
  type: "object",
  properties: {
    username: { type: "string", minLength: 3 },
    email: { type: "string", format: "email" }
  },
  required: ["username", "email"]
};

const validate = ajv.compile(schema);
const data = { username: "abc", email: "test@example.com" };

if (!validate(data)) {
  console.log("验证失败:", validate.errors);
} else {
  console.log("验证通过");
}

2. 配置文件验证

确保应用配置文件格式正确：

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "应用配置",
  "type": "object",
  "properties": {
    "port": { "type": "integer", "minimum": 1, "maximum": 65535 },
    "database": {
      "type": "object",
      "properties": {
        "host": { "type": "string" },
        "port": { "type": "integer" },
        "name": { "type": "string" }
      },
      "required": ["host", "name"]
    }
  },
  "required": ["port"]
}

六、常用验证工具

七、最佳实践

八、总结

JSON Schema 是数据验证的强大工具，能够：

• 提高数据质量，减少运行时错误
• 作为 API 文档的一部分，自动生成接口说明
• 在前后端之间建立数据契约
• 支持自动化测试和数据校验

掌握 JSON Schema，让你的数据处理更加规范和可靠！