简介

JSON Schema是一种用于描述 JSON 数据结构的规范，它提供了一种标准化的方式来定义JSON的数据格式、验证规则以及约束，使得开发者可以确保传递的数据符合预期的结构和格式。通常我们把它用来描述 OpenAPI 的入参和出参。

相关文档：
https://json-schema.org/draft/2020-12/json-schema-core#rfc.section-8

基本数据类型

• string：字符串类型
• number：数字类型
• integer：整数类型
• boolean：布尔类型
• array：数组类型
• object：对象类型
• null：空值

关键字

• type: 指定数据的类型，如 string、object
• properties: 定义对象的属性及其类型。
• required：定义哪些属性是必需的。
• items：定义数组中的元素类型。
• enum：指定允许的值列表。
• minLength / maxLength：限制字符串的最小和最大长度。
• minimum / maximum：限制数字或整数的最小和最大值。
• minItems: 数组最小的额元素个数
• uniqueItems: 数组内的元素不能重复
• exclusiveMinimum / exclusiveMaximum: 限制数字或整数的最小和最大值(不包含)
• pattern：使用正则表达式限制字符串的格式。
• additionalProperties：控制对象是否允许未定义的属性。

使用介绍

在 JSON Schema 中，你可以为每个属性添加 title 和 description。

• title：简要描述字段的名称或功能。
• description：详细说明字段的含义、用途或额外信息。

对象

假设有个Product Json，其中tags为可选字段，其它几个字段必填。如果传了tags，其元素最小为1，元素不能重复。
json

{"productId": 1,"productName": "A green door","price": 12.50,"tags": [ "home", "green" ]
}

**json schema

{"$schema": "https://json-schema.org/draft/2020-12/schema","title": "Product","description": "A product from Acme's catalog","type": "object","properties": {"productId": {"description": "The unique identifier for a product","type": "integer"},"productName": {"description": "Name of the product","type": "string"},"price": {"description": "The price of the product","type": "number","exclusiveMinimum": 0},"tags": {"description": "Tags for the product","type": "array","items": {"type": "string"},"minItems": 1,"uniqueItems": true}},"required": [ "productId", "productName", "price" ]
}

数组

json

[{"id": 1,"name": "Alice","email": "alice@example.com"},{"id": 2,"name": "Bob","email": "bob@example.com"}
]

json schema

{"$schema": "https://json-schema.org/draft/2020-12/schema","title": "user list","type": "array","items": {"type": "object","properties": {"id": {"type": "integer","title": "User ID","description": "A unique identifier for the user"},"name": {"type": "string","title": "Full Name","description": "The user's full name"},"email": {"type": "string","format": "email","title": "Email Address","description": "The user's email address, must be a valid email format"}},"required": ["id", "name", "email"]}
}

多类型数组
dubbo接口的参数会序列化成数组，方法的每个位置类型可能都不一样，json-schema支持为数组的每个元素分别定义类型描述。
接口：[1, 'zhangsan']可以用下面的json-schema描述

{"type": "array","items": [{ "type": "integer" },{ "type": "string" }],"minItems": 2,"maxItems": 2
}

对象嵌套

当某个属性不是基本类型时，需要用到对象嵌套，具体根据类型选择上面的对象或者数组格式。
json

{"id": 1,"name": "Alice","email": "alice@example.com","address": {"street": "123 Main St","city": "Wonderland","zipcode": "12345","country": "Wonderland Country"}
}

json schema

{"$schema": "http://json-schema.org/draft-07/schema#","title": "user detail","type": "object","properties": {"id": {"type": "integer","title": "User ID","description": "A unique identifier for the user"},"name": {"type": "string","title": "Full Name","description": "The user's full name"},"email": {"type": "string","format": "email","title": "Email Address","description": "The user's email address, must be a valid email format"},"address": {"type": "object","properties": {"street": {"type": "string","title": "Street","description": "The street address"},"city": {"type": "string","title": "City","description": "The city name"},"zipcode": {"type": "string","title": "Zipcode","description": "The postal code"},"country": {"type": "string","title": "Country","description": "The country name"}},"required": ["street", "city", "zipcode", "country"]}},"required": ["id", "name", "email", "address"]
}

map属性

这里假设settings属性是Map类型。map用object类型描述，额外多了一个additionalProperties字段，用于描述map所存的value格式，可以是简单类型、数组或者是嵌套对象类型。
json

{"id": 1,"name": "Alice","settings": {"theme": "dark","notifications": "enabled","language": "en"}
}

json schema

{"$schema": "http://json-schema.org/draft-07/schema#","type": "object","title": "map字段展示","properties": {"id": {"type": "integer","title": "User ID","description": "A unique identifier for the user"},"name": {"type": "string","title": "Full Name","description": "The user's full name"},"settings": {"type": "object","title": "Settings Map","description": "A map of user settings","additionalProperties": {"type": "string","description": "The value for each setting"}}},"required": ["id", "name", "settings"]
}