JSON Schema属性使用汇总

JSON Schema 除了 type 属性外，还提供了许多其他属性来定义数据结构的约束和验证规则。以下是一些常用的属性和它们的描述：

常见的 JSON Schema 属性

1. $schema

• 描述：指定当前 JSON Schema 使用的草案版本（通常是 http://json-schema.org/draft-07/schema#，也可以是其他版本，如 http://json-schema.org/draft-06/schema#）。
• 示例：

  "$schema": "http://json-schema.org/draft-07/schema#"
  

2. type

• 描述：定义数据的类型，可以是以下类型之一：string、number、integer、object、array、boolean、null。可以使用数组表示多个类型。
• 示例：

  "type": "string"
  

3. properties

• 描述：用于对象类型的字段，定义对象的属性及其类型。
• 示例：

  "properties": {
    "name": {
      "type": "string"
    },
    "age": {
      "type": "integer"
    }
  }
  

4. required

• 描述：指定对象中必需的属性，值是一个数组，包含必须存在的属性名称。
• 示例：

  "required": ["name", "age"]
  

5. enum

• 描述：定义一个值的集合，表示该字段的值必须是某些指定值之一。
• 示例：

  "enum": ["small", "medium", "large"]
  

6. additionalProperties

• 描述：对于对象类型，指定是否允许对象有额外的属性。可以是 true 或 false，如果是 false，则表示对象不能包含未定义的属性。
• 示例：

  "additionalProperties": false
  

7. items

• 描述：用于数组类型，定义数组元素的类型或结构。如果数组元素的结构是相同的，使用 items 定义；如果结构不同，则可以使用 oneOf 或 anyOf。
• 示例：

  "items": {
    "type": "string"
  }
  

8. minLength / maxLength

• 描述：对于 string 类型，minLength 和 maxLength 分别指定字符串的最小长度和最大长度。
• 示例：

  "minLength": 3,
  "maxLength": 10
  

9. minItems / maxItems

• 描述：对于数组类型，minItems 和 maxItems 分别指定数组的最小长度和最大长度。
• 示例：

  "minItems": 1,
  "maxItems": 5
  

10. minimum / maximum

• 描述：用于 number 或 integer 类型，指定值的最小值和最大值。可以使用 exclusiveMinimum 和 exclusiveMaximum 来指定是否排除最小或最大值。
• 示例：

  "minimum": 10,
  "maximum": 100
  

11. pattern

• 描述：对于 string 类型，使用正则表达式来指定字符串值的格式。
• 示例：

  "pattern": "^[a-zA-Z0-9]+$"
  

12. format

• 描述：指定字符串的格式（如日期、时间、邮箱等）。常见的格式包括：
  • date（YYYY-MM-DD）
  • time（HH:MM:SS）
  • date-time（完整日期时间）
  • email（电子邮件地址）
  • uri（URI）
  • hostname（主机名）
  • ipv4（IPv4 地址）
  • ipv6（IPv6 地址）
• 示例：

  "format": "date-time"
  

13. default

• 描述：指定字段的默认值。当数据中未提供该字段时，会使用默认值。
• 示例：

  "default": "N/A"
  

14. allOf

• 描述：用于组合多个模式，表示数据必须符合所有给定的模式。
• 示例：

  "allOf": [
    { "type": "string" },
    { "minLength": 3 }
  ]
  

15. anyOf

• 描述：用于组合多个模式，表示数据可以符合其中的任何一个模式。
• 示例：

  "anyOf": [
    { "type": "string" },
    { "type": "number" }
  ]
  

16. oneOf

• 描述：用于组合多个模式，表示数据必须符合其中一个模式，不能同时符合多个模式。
• 示例：

  "oneOf": [
    { "type": "string" },
    { "type": "integer" }
  ]
  

17. not

• 描述：表示数据不能符合给定的模式。
• 示例：

  "not": {
    "type": "string"
  }
  

18. dependencies

• 描述：定义一个属性的存在依赖于另一个属性的存在。它可以是一个对象或数组。
• 示例：

  "dependencies": {
    "zipCode": ["state", "city"]
  }
  

19. if, then, else

• 描述：表示条件约束，如果 if 中的条件为真，则应用 then 部分的验证规则，否则应用 else 部分的规则。
• 示例：

  "if": {
    "properties": { "type": { "const": "VIP" } }
  },
  "then": {
    "properties": { "discount": { "type": "number" } }
  },
  "else": {
    "properties": { "discount": { "type": "null" } }
  }
  

额外属性：

• title：提供模式的标题。
• description：提供模式的描述。
• examples：提供有效数据的示例。
• $ref：引用其他模式定义，支持循环引用和模式复用。

示例：完整的 JSON Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "age": {
      "type": "integer",
      "minimum": 18,
      "maximum": 120
    },
    "email": {
      "type": "string",
      "format": "email"
    }
  },
  "required": ["name", "age"],
  "additionalProperties": false
}

这个 JSON Schema 定义了一个对象，包含 name（字符串）、age（整数）和 email（电子邮件格式）。其中 name 和 age 是必填字段，并且限制了 age 的范围在 18 到 120 之间。同时禁止出现任何未定义的附加属性。