JSON Schema

Links

• [1] https://json-schema.apifox.cn/
• [2] https://json-schema.org/
• [3] API 清单：https://www.learnjsonschema.com/

Notes

Type-specific keywords

https://json-schema.org/understanding-json-schema/reference/type

• type：string、number、integer、object、array、boolean、null
• with type string
  • Length：minLength、maxLength
  • pattern(正则表达式)
  • Dates and times
    • date-time：2018-11-13T20:20:39+00:00
    • time：20:20:39+00:00
    • date：2018-11-13
    • duration：P3D（3 天）
  • Hostnames：hostname、idn-hostname
  • IP Addresses：ipv4、ipv6
  • Resource identifiers：uuid、uri、uri-reference、iri、iri-reference
  • URI template：uri-template
  • JSON Pointer：json-pointer、relative-json-pointer
  • Regular Expressions：regex
• with type number
  • multiples：multipleOf（倍数，可以设置成任何正数）
  • range：minimum、exclusiveMinimum、exclusiveMinimum、maximum、exclusiveMaximum
• with type object
  • properties
  • patternProperties：正则表达式用于 key
  • additionalProperties：如果为 false，那么不允许有其他的 propertites
  • unevaluatedProperties：类似于additionalProperties，只是它可以识别在子架构中声明的属性。
  • required：必须包含的properties，是一个array
  • propertyNames：属性名称。如果您不想强制使用特定的属性，但又想确保这些属性的名称遵循特定的约定，那么这会很有用。
  • 属性的数量：minProperties、maxProperties

例如：

{
  "type": "object",
  "properties": {
    "number": { "type": "number" },
    "street_name": { "type": "string" },
    "street_type": { "enum": ["Street", "Avenue", "Boulevard"] }
  },
  "patternProperties": {
    "^S_": { "type": "string" }, <- 任何 S_ 开头的key 对应的 value 都必须是 string
  }
  "additionalProperties": false,
  // "additionalProperties": { "type": "string" } <- 这样就可以允许 string 的属性
}

• with type array
  • prefixItems：元组验证（一个固定长度的序列，其中每个项目可能具有不同的模式）
  • unevaluatedItems：数组中添加或禁止额外项时有用和 items 有点像
  • items：列表验证（一个任意长度的序列，其中每个项目匹配相同的模式）。items用来验证超出prefixItems中定义的元素是否有效，如果为 false 则不能包含其他项目
  • minItems、maxItems：数组长度
  • contains：有一个满足就行
  • minContains、maxContains：进一步控制 contains 达标的数量
  • uniqueItems：确保数组中的每个项都是唯一的

{
  "type": "array",
  "prefixItems": [
    { "type": "number" },
    { "type": "string" },
    { "enum": ["Street", "Avenue", "Boulevard"] },
    { "enum": ["NW", "NE", "SW", "SE"] }
  ],
  "items": false
}

{
  "prefixItems": [
    { "type": "string" }, { "type": "number" }
  ],
  "unevaluatedItems": false
}

• with type boolean（只能是 true 或 false）
• with type null（只能是 null，其他的比如 false，0，"" 都不可以）

Schema Composition

https://json-schema.org/understanding-json-schema/reference/combining#schema-composition

• allOf: (AND) Must be valid against all of the subschemas
• anyOf: (OR) Must be valid against any of the subschemas
• oneOf: (XOR) Must be valid against exactly one of the subschemas
• not：非

Examples：

需要同时满足

{
  "allOf": [
    { "type": "string" },
    { "maxLength": 5 }
  ]
}

满足其一就行

{
  "anyOf": [
    { "type": "string", "maxLength": 5 },
    { "type": "number", "minimum": 0 }
  ]
}

满足一个

{
  "oneOf": [
    { "type": "number", "multipleOf": 5 },
    { "type": "number", "multipleOf": 3 }
  ]
}

非

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