引言
JSON Schema 是一种用于描述和验证 JSON 数据结构的规范。它定义了 JSON 数据中各个元素的类型、格式、约束和关系,确保了数据的一致性和可靠性。在软件开发、API 设计以及数据交换过程中,JSON Schema 发挥着重要作用。本文将详细介绍 JSON Schema 的格式、关键字段以及具体案例。
JSON Schema 的格式
JSON Schema 本身也是一段 JSON 格式的数据,它通过键值对来定义 JSON 数据的结构和内容。以下是一个 JSON Schema 的基本结构示例:
示例1
{ "$schema": "http://json-schema.org/draft-07/schema#", "title": "示例 Schema", "description": "描述信息", "type": "object", "properties": { "name": { "type": "string", "description": "名称" }, "age": { "type": "integer", "minimum": 0, "description": "年龄" } }, "required": ["name", "age"]
}
针对上诉示例进行逐行讲解!
关键字段详解
$schema
- 作用:指定 JSON Schema 的版本信息,例如
"http://json-schema.org/draft-07/schema#"
表示使用 JSON Schema 的 Draft 07 版本。 - 是否可省略:可以省略,但推荐保留以便明确版本。
title 和 description
- 作用:提供 JSON Schema 的标题和描述信息,帮助人类理解 Schema 的内容和目的。
- 是否可省略:可以省略,但保留有助于文档化。
type
- 作用:定义 JSON 数据的类型,如
"object"
,"array"
,"string"
,"number"
,"integer"
,"boolean"
,"null"
。 - 示例:
"type": "object"
表明 JSON 数据是一个对象。"type": "array"
表明 JSON 数据是一个列表。"type": "string"
表明 JSON 数据是一个字符串。"type": "number"
表明 JSON 数据是一个数字(可以是整型也可以是浮点型)。"type": "integer"
表明 JSON 数据是一个整型。"type": "boolean"
表明 JSON 数据是一个bool型。"type": "null"
表明 JSON 数据是一个空。
properties
- 作用:在
type
为"object"
时使用,定义对象中的属性及其类型、约束等。 - 示例:
"properties": { "name": {"type": "string"}, "age": {"type": "integer", "minimum": 0, "maxinum": 10} }
required
- 作用:定义 JSON 对象中必须存在的属性列表。
- 示例:
"required": ["name", "age"]
表示 JSON 对象中必须包含name
和age
属性。
minimum、maximum
- 作用:用于定义数字的最小值和最大值。
- 示例:如上
示例2
{ "$schema": "http://json-schema.org/draft-07/schema#", "title": "复杂数组Schema示例", "type": "array", "uniqueItems": true, "items": { "type": "object", "properties": { "status": { "type": "string", "enum": ["active", "inactive", "pending"] }, "startDate": { "type": "string", "format": "date-time", "examples": ["2023-04-01T12:00:00Z"] }, "age": { "type": "number", "exclusiveMinimum": 0, "exclusiveMaximum": 150 }, "username": { "type": "string", "minLength": 3, "maxLength": 20, "pattern": "^[a-zA-Z0-9_]+$" } }, "required": ["status", "startDate", "age", "username"] }
}
关键字段详解
uniqueItems
- 作用:当
type
为array
时,指定数组中的元素是否必须唯一
items
- 作用:在
type
为"array"
时使用,定义数组元素的类型或结构。 - 示例:
"type": "array", "items": { "type": "string", "maxLength": 5 }
enum
作用:定义了一个值的集合,该字段的值必须是集合中的一个。
示例:如上
format
作用:用于定义字符串的格式,如email
、date-time
等。
需要注意的是,
format
关键字的验证行为可能依赖于实现,因为它不是JSON Schema规范的核心部分。
exclusiveMinimum、exclusiveMaximum
作用:类似minimum
和maximum
,额外表示边界值是否包含在允许的范围内。
minLength、maxLength
作用:用于定义字符串的最小和最大长度。
pattern
作用:用于定义字符串必须匹配的正则表达式。