---

一、引言

在現代的 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