JSON Schema 入门指南：如何定义和验证 JSON 数据结构

一、引言

在现代的 Web 开发和数据交换中，JSON（JavaScript Object Notation）已经成为了一种非常流行的数据格式。它轻量、易读、易于解析，广泛应用于 API 通信、配置文件、数据存储等场景。然而，随着 JSON 数据结构的复杂性增加，如何确保 JSON 数据的有效性和一致性成为了一个挑战。这时，JSON Schema 就派上了用场。

本文将带你入门 JSON Schema，帮助你理解它的基本概念、语法结构，并通过实例演示如何使用 JSON Schema 来定义和验证 JSON 数据结构。

二、什么是 JSON Schema？

JSON Schema 是一种用于描述 JSON 数据结构的规范。它允许你定义 JSON 数据的格式、类型、约束条件等，从而确保 JSON 数据符合预期的结构。通过 JSON Schema，你可以在数据交换、存储或处理之前，对 JSON 数据进行验证，确保其有效性和一致性。

简单来说，JSON Schema 就像是 JSON 数据的“蓝图”或“合同”，它规定了 JSON数据应该长什么样子。

三、JSON Schema 的基本结构

一个 JSON Schema 本身也是一个 JSON 对象。它由一系列关键字（keywords）组成，这些关键字用于定义 JSON 数据的结构和约束条件。

3.1 基本关键字

• $schema: 指定使用的 JSON Schema 版本。例如，"$schema": "http://json-schema.org/draft-07/schema#" 表示使用 Draft 7 版本的 JSON Schema。
• $id: 为 Schema 定义一个唯一的标识符，通常是一个 URL。
• title 和 description: 分别为 Schema 提供标题和描述信息，便于理解和维护。
• type: 定义 JSON 数据的类型。常见的类型有 object、array、string、number、integer、boolean 和 null。

3.2 对象属性

• properties: 定义对象中的各个属性及其对应的 Schema。
• required: 指定哪些属性是必须的。
• additionalProperties: 控制是否允许对象包含未在 properties 中定义的额外属性。

3.3 数组元素

• items: 定义数组中每个元素的 Schema。
• minItems 和 maxItems: 分别指定数组的最小和最大长度。
• uniqueItems: 指定数组中的元素是否必须唯一。

3.4 字符串约束

• minLength 和 maxLength: 分别指定字符串的最小和最大长度。
• pattern: 使用正则表达式约束字符串的格式。
• format: 指定字符串的格式，如 email、date-time 等。

3.5 数值约束

• minimum 和 maximum: 分别指定数值的最小和最大值。
• exclusiveMinimum 和 exclusiveMaximum: 指定数值是否排除最小值和最大值。
• multipleOf: 指定数值必须是某个数的倍数。

四、示例：定义一个简单的 JSON Schema

假设我们要定义一个表示用户信息的 JSON 数据结构，要求如下：

• 用户对象必须包含 id、name 和 email 属性。
• id 必须是整数。
• name 必须是字符串，且长度在 1 到 50 之间。
• email 必须是有效的电子邮件地址。
• 用户对象可以包含可选的 age 属性，且必须是正整数。

对应的 JSON Schema 可以这样定义：

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://example.com/user.schema.json",
  "title": "User",
  "description": "A user object",
  "type": "object",
  "properties": {
    "id": {
      "type": "integer"
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 50
    },
    "email": {
      "type": "string",
      "format": "email"
    },
    "age": {
      "type": "integer",
      "minimum": 0,
      "exclusiveMinimum": true
    }
  },
  "required": ["id", "name", "email"],
  "additionalProperties": false
}

解释

• $schema 和 $id 分别指定了 Schema 的版本和唯一标识符。
• type 指定了 JSON 数据的类型为 object。
• properties 定义了对象的各个属性及其约束条件。
• required 指定了 id、name 和 email 是必须的属性。
• additionalProperties 设置为 false，表示不允许对象包含未定义的属性。

五、使用 JSON Schema 进行验证

定义好 JSON Schema 后，我们可以使用各种工具和库来验证 JSON 数据是否符合该 Schema。以下是一些常用的验证工具：

• JavaScript: 可以使用 Ajv 库进行验证。
• Python: 可以使用 jsonschema 库进行验证。
• 在线工具: 可以使用 JSON Schema Validator 在线验证 JSON 数据。

示例：使用 Ajv 进行验证
假设我们有以下 JSON 数据：

 
{
  "id": 1,
  "name": "John Doe",
  "email": "john.doe@example.com",
  "age": 30
}

我们可以使用 Ajv 来验证该数据是否符合我们定义的 Schema：

const Ajv = require('ajv');
const ajv = new Ajv();

const schema = {
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://example.com/user.schema.json",
  "title": "User",
  "description": "A user object",
  "type": "object",
  "properties": {
    "id": {
      "type": "integer"
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 50
    },
    "email": {
      "type": "string",
      "format": "email"
    },
    "age": {
      "type": "integer",
      "minimum": 0,
      "exclusiveMinimum": true
    }
  },
  "required": ["id", "name", "email"],
  "additionalProperties": false
};

const data = {
  "id": 1,
  "name": "John Doe",
  "email": "john.doe@example.com",
  "age": 30
};

const validate = ajv.compile(schema);
const valid = validate(data);

if (valid) {
  console.log('数据有效');
} else {
  console.log('数据无效:', validate.errors);
}

如果数据符合 Schema，输出将是 数据有效；否则，输出将是 数据无效 并显示具体的错误信息。

六、实战效果

我们以 Furion 框架为例，Furion 框架提供了完整的 Furion 和 ASP.NET Core 的 JSON Schema 文件，通过该文件可以在编写配置文件时提供完整的智能提示和校验。

6.1 如何使用

使用方式非常简单，只需要在 .json 文件的头部添加 "$schema":"https://gitee.com/dotnetchina/Furion/raw/v4/schemas/v4/furion-schema.json", 即可，
如：

{
  "$schema": "https://gitee.com/dotnetchina/Furion/raw/v4/schemas/v4/furion-schema.json",

  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information",
      "Microsoft.EntityFrameworkCore": "Information",
      "Microsoft.AspNetCore.HttpLogging.HttpLoggingMiddleware": "Information"
    }
  },
  "AllowedHosts": "*"
}

怎么样，这会知道好处了把！！

七、总结

JSON Schema 是一种强大的工具，可以帮助你定义和验证 JSON 数据的结构。通过使用 JSON Schema，你可以确保 JSON 数据的有效性和一致性，减少数据错误和异常情况的发生。本文介绍了 JSON Schema 的基本概念、语法结构，并通过实例演示了如何定义和使用 JSON Schema。

希望这篇入门指南能帮助你更好地理解和使用 JSON Schema。如果你有更多问题或需要进一步的帮助，欢迎在评论区留言讨论！

参考资料:

• JSON Schema 官方文档
• Ajv 文档
• JSON Schema Validator