JSON Schema

简介

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"]
}