3. JSON Schema 入门：定义 Redis Value 的契约

在 Redis 契约校验体系中，JSON Schema 是描述 Value 结构最核心的语言。它不关心数据如何存储，只关心数据“应该长什么样”。本章从零开始，掌握 JSON Schema 的基本语法、关键字，并学会为 Redis Value 编写精确的 Schema 定义。

3.1 什么是 JSON Schema

JSON Schema 是一种基于 JSON 格式的声明式语言，用于描述 JSON 数据的结构、类型和约束。你可以把它理解为“数据的身份证”——它规定了某个 JSON 对象必须包含哪些字段、字段的类型是什么、取值范围是多少。

3.2 基本语法与结构

一个最简单的 JSON Schema 通常包含以下结构：

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://example.com/user-schema.json",
  "title": "User Profile",
  "description": "用户基本信息 Schema",
  "type": "object",
  "properties": {
    "username": { "type": "string" },
    "age": { "type": "integer" }
  },
  "required": ["username"]
}

3.3 核心关键字详解

3.3.1 类型约束

type 是最基础的关键字，支持以下 7 种类型：

• string — 字符串
• number — 数字（整数或浮点数）
• integer — 整数
• boolean — 布尔值
• object — 对象
• array — 数组
• null — 空值

3.3.2 字符串约束

3.3.3 数字约束

3.3.4 数组约束

3.3.5 对象约束

3.4 如何定义 Redis Value 的 Schema

在 Redis 中，Value 可以是任意 JSON 结构。定义 Schema 时，需要先确定 Value 的顶层类型，然后逐层描述内部字段。

步骤流程：

1. 确定顶层类型 — 通常是 object 或 array
2. 列出所有字段 — 使用 properties 定义每个字段
3. 标记必填字段 — 使用 required 列出必须存在的字段名
4. 约束字段类型 — 为每个字段设置 type 和附加约束
5. 控制额外字段 — 使用 additionalProperties 决定是否允许未声明的字段

{
  "userId": "u_1001",
  "role": "admin",
  "loginCount": 42,
  "tags": ["vip", "2024"],
  "profile": {
    "nickname": "Alice",
    "avatar": "https://example.com/avatar.png"
  }
}

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "User Session",
  "type": "object",
  "properties": {
    "userId": {
      "type": "string",
      "pattern": "^u_\\d+$",
      "description": "用户ID，以 u_ 开头"
    },
    "role": {
      "type": "string",
      "enum": ["admin", "user", "guest"]
    },
    "loginCount": {
      "type": "integer",
      "minimum": 0
    },
    "tags": {
      "type": "array",
      "items": { "type": "string" },
      "minItems": 1,
      "uniqueItems": true
    },
    "profile": {
      "type": "object",
      "properties": {
        "nickname": { "type": "string", "minLength": 1 },
        "avatar": { "type": "string", "format": "uri" }
      },
      "required": ["nickname"],
      "additionalProperties": false
    }
  },
  "required": ["userId", "role", "loginCount"],
  "additionalProperties": false
}

3.5 JSON Schema 校验流程

3.6 常见避坑指南

3.7 本章小结

• JSON Schema 是描述 JSON 数据结构的声明式语言，核心关键字包括 type、properties、required、additionalProperties 等。
• 字符串、数字、数组、对象各有专属约束关键字，如 pattern、minimum、minItems、uniqueItems。
• 定义 Redis Value 的 Schema 时，先确定顶层类型，再逐层描述字段，最后通过 required 和 additionalProperties 控制严格程度。
• 校验流程分为加载 Schema、逐字段校验、输出通过/失败结果三个步骤。