Papyrus.
go-mcp / 【前置】json schema.md

【前置】json schema

最后更新 2026-06-24

什么是 JSON Schema?

JSON Schema 是一种用于验证 JSON 数据结构的标准规范。它定义了 JSON 文档应该如何构造，包括数据类型、必需字段、值的范围等约束条件。

简单来说，JSON Schema 就是用来描述和验证 JSON 数据的格式规范。

如果把 JSON 比作一份数据文档，那么 JSON Schema 就是这份文档的"模板"或"格式要求"：

  • JSON: 实际的数据内容
  • JSON Schema: 数据应该符合的规则

完整示例

假设有一个用户信息的 JSON 对象：

{
  "id": 1,
  "name": "张三",
  "email": "zhangsan@example.com",
  "age": 28,
  "roles": ["user", "admin"]
}

现在，我们需要定义一个 Schema 来描述上面 JSON 应该符合的规则：

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": { "type": "integer" },
    "name": { "type": "string" },
    "email": { "type": "string", "format": "email" },
    "age": { "type": "integer", "minimum": 18, "maximum": 120 },
    "roles": { 
      "type": "array",
      "items": { "type": "string" },
      "minItems": 1
    }
  },
  "required": ["id", "name", "email"]
}

Schema 中各部分的含义：

  • type: "object" — 定义该 JSON 是一个对象
  • properties — 定义对象包含的属性和它们的类型
  • id: integer — id 字段必须是整数
  • name: string — name 字段必须是字符串
  • email: string, format: email — email 必须是字符串，且格式必须是有效的邮箱
  • age: integer, minimum: 18, maximum: 120 — age 必须是整数，且在 18 到 120 之间
  • roles: array, items: string — roles 必须是数组，且数组中的每个元素都是字符串
  • required: ["id", "name", "email"] — 这三个字段是必需的

验证结果：

✅ 有效的 JSON（符合上面的 Schema）：

{
  "id": 1,
  "name": "张三",
  "email": "zhangsan@example.com",
  "age": 28,
  "roles": ["user", "admin"]
}

❌ 无效的 JSON（违反了 Schema 规则）：

{
  "id": "不是数字",
  "name": "李四",
  "email": "不是有效邮箱",
  "age": 15,
  "roles": ["user"]
}

违反原因：

  • id 不是整数
  • email 格式不是有效邮箱
  • age 小于最小值 18
  • 缺少了 required 中的某个字段

核心概念

1. 基本属性

一个最简单的 Schema 包含以下基本信息：

JSON 数据：

{
  "firstName": "张",
  "lastName": "三"
}

对应的 Schema：

{
  "type": "object",
  "properties": {
    "firstName": { "type": "string" },
    "lastName": { "type": "string" }
  },
  "required": ["firstName", "lastName"]
}

关键字解释：

  • type: 数据类型（object、array、string、number、boolean、null）
  • properties: 定义对象的属性及其类型
  • required: 指定哪些字段是必需的

2. 数据类型约束

JSON 数据：

{
  "age": 28,
  "score": 95.5,
  "name": "张三",
  "active": true,
  "tags": ["golang", "web"]
}

对应的 Schema：

{
  "type": "object",
  "properties": {
    "age": { "type": "integer", "minimum": 0, "maximum": 150 },
    "score": { "type": "number", "minimum": 0, "maximum": 100 },
    "name": { "type": "string", "minLength": 1, "maxLength": 50 },
    "active": { "type": "boolean" },
    "tags": { "type": "array", "items": { "type": "string" } }
  }
}

3. 格式验证

JSON 数据：

{
  "email": "user@example.com",
  "website": "https://example.com",
  "birthday": "2000-01-01",
  "timestamp": "2024-01-01T12:00:00Z"
}

对应的 Schema：

{
  "type": "object",
  "properties": {
    "email": { "type": "string", "format": "email" },
    "website": { "type": "string", "format": "uri" },
    "birthday": { "type": "string", "format": "date" },
    "timestamp": { "type": "string", "format": "date-time" }
  }
}

4. 枚举和模式

JSON 数据：

{
  "status": "active",
  "phone": "123-456-7890"
}

对应的 Schema：

{
  "type": "object",
  "properties": {
    "status": { "enum": ["active", "inactive", "pending"] },
    "phone": { "type": "string", "pattern": "^\\d{3}-\\d{3}-\\d{4}$" }
  }
}

常用关键字

关键字 说明 示例
type 数据类型 "string", "integer"
properties 对象属性定义 {"name": {...}}
required 必需字段 ["id", "name"]
items 数组元素的类型 {"type": "string"}
minimum 最小值 0
maximum 最大值 100
minLength 最小长度 1
maxLength 最大长度 50
pattern 正则表达式 "^[a-z]+$"
enum 枚举值 ["a", "b", "c"]
format 格式检查 "email", "uri"

学习资源