jsonschema 模式校验

jsonschema 4.17.4.dev58+gcb1f8af documentation

pip install jsonschema -i https://mirrors.aliyun.com/pypi/simple/

 1. 什么是模式

What is a schema? — Understanding JSON Schema 2020-12 documentation

如果你曾经使用过 XML Schema,RelaxNG 或 ASN.1,那么你可能已经知道什么是模式,并且可以高兴地跳到下一节。如果你听起来像个傻瓜,那你来对地方了。要定义什么是 JSON 模式,我们可能应该首先定义什么是 JSON。

JSON 代表JavaScript 对象表示法,这是一种简单的数据交换格式。它最初是作为万维网的一种表示法。由于大多数网络浏览器中都存在 JavaScript,并且 JSON 基于 JavaScript,因此很容易在其中进行支持。但是,它已经被证明足够有用和足够简单,现在可以在许多不涉及网络冲浪的情况下使用它。

JSON 本质上是基于以下数据结构构建的:


  • object:
    { "key1": "value1", "key2": "value2" }
    
  • array:
    [ "first", "second", "third" ]
    

  • number:
    42
    3.1415926
    

  • string:
    "This is a string"
    

  • boolean:
    true
    false
    

  • null:
    null

 

这些类型在大多数编程语言中都有类似物,尽管它们的名称可能不同。

下表从 JavaScript 类型的名称映射到 Python 中的类似类型:

JavaScript Python
string string
number int/float
object dict
array list
boolean bool
null None

 

JavaScript 没有针对整数和浮点数的单独类型。

使用这些简单的数据类型,可以表示所有类型的结构化数据。但是,随着灵活性的提高,责任也就增加了,因为同一概念可以用多种方式表示。例如,你可以想象以不同的方式用 JSON 表示有关一个人的信息:

{
  "姓名": "张三",
  "出生日期": "1990年01月01日",
  "地址": "中国广东省深圳市宝安区"
}

{
  "姓": "张",
  "名": "三",
  "出生日期": "1990-01-01",
  "地址": {
    "国家": "中国",
    "省": "广东省",
    "市": "深圳市",
    "区": "宝安区"
  }
}

 

两种陈述都同样有效,尽管其中一种显然比另一种更为正式。记录的设计将在很大程度上取决于其在应用程序中的预期用途,因此这里没有正确或错误的答案。但是,当应用程序说“给我一个人的 JSON 记录”时,准确知道该记录的组织方式非常重要。

例如,我们需要知道需要哪些字段以及如何表示值。

这就是 JSON Schema 的来源。以下 JSON Schema 片段描述了上面第二个示例的结构。现在不必担心太多细节。在随后将对它们进行说明。

{
  "type": "object",
  "properties": {
    "姓": { "type": "string" },
    "名": { "type": "string" },
    "出生日期": { "type": "string", "format": "date" },
    "地址": {
      "type": "object",
      "properties": {
        "国家": { "type": "string" },
        "省": { "type": "string" },
        "市": { "type": "string" },
        "区": { "type" : "string" }
      }
    }
  }
}

通过针对该模式“验证”第一个示例,你可以看到它失败了。但是,第二个示例通过了:

你可能已经注意到 JSON Schema 本身是用 JSON 编写的。它是数据本身,而不是计算机程序。它只是“描述其他数据的结构”的声明性格式。

这既是它的强项,也是它的弱项(与其他类似的模式语言共享)。简明扼要地描述数据的表面结构,并根据它自动进行数据验证很容易。

但是,由于 JSON 模式不能包含任意代码,因此无法表达的数据元素之间的关系受到某些限制。

因此,任何用于足够复杂的数据格式的“验证工具”都可能具有两个验证阶段:一个在模式(或结构)级别,另一个在语义级别。后者检查可能需要使用更通用的编程语言来实现。

2.官网总纲

JSON Schema Tool

3.JSON 模式参考

JSON Schema Reference — Understanding JSON Schema 2020-12 documentation

3.1 特定类型的关键字

  • 字符串:string
  • 数值类型:integer、number、Multiples、Range
  • 对象:object
  • 数组:array
  • 布尔值:boolean
  • 空:null
{ "type": "number" }
// 成功:10、20.5
// 失败:"10"

{ "type": ["number", "string"] }
// 成功:10、20.5、"10"、"你好"
// 失败:[1, 2, 3]

type 关键字可以是一个字符串或数组:

  • 如果是字符串,则为上述基本类型之一的名称。
  • 如果是数组,则必须是字符串数组,其中每个字符串是一种基本类型的名称,并且每个元素都是唯一的。在这种情况下,如果 JSON 代码段与任何给定类型匹配,则该代码段有效。

3.2  正则表达式

该模式和模式属性关键字使用正则表达式来表示约束。使用的正则表达式语法来自 JavaScript(尤其是 ECMA 262)。

但是,不完全支持完整的语法,因此建议你坚持下面描述的该语法的子集。

  • 单个 unicode 字符(下面的特殊字符除外)与自己匹配。
  • .:匹配除换行符以外的任何字符。(请注意,组成换行符的内容在某种程度上取决于你的平台和语言环境,但实际上这并不重要)。
  • ^:仅在字符串开头匹配。
  • $:仅在字符串末尾匹配。
  • (...):将一系列正则表达式分组为一个正则表达式。
  • |:匹配|符号之前或之后的正则表达式。
  • [abc]:匹配方括号内的任何字符。
  • [a-z]:匹配字符范围。
  • [^abc]:匹配未列出的任何字符。
  • [^a-z]:匹配范围之外的任何字符。
  • +:匹配前一个正则表达式的一个或多个重复。
  • *:匹配零个或多个前面的正则表达式重复。
  • ?:匹配前一个正则表达式的零个或一个重复。
  • +?*???:的*+ 和?预选赛都是贪婪的;它们匹配尽可能多的文本。有时,这种行为是不希望的,并且你想要匹配的字符越少越好。
  • (?!x)(?=x):阴性和阳性预测先行。
  • {x}:精确 x 匹配前面的正则表达式的出现。
  • {x,y}:至少匹配 x 并且最多 y 匹配前面的正则表达式。
  • {x,}:匹配 x 出现的一个或多个前面的正则表达式。
  • {x}?{x,y}?{x,}?:上述表达式的非贪婪版本。

腾讯 QQ 号:纯数字,至少 5 位

{
   "type": "string",
   "pattern": "^[1-9][0-9]{4,}$"
}

3.3  数值类型

  •  integer

        integer 类型用于整数。在 Python 中,类似于该 int 类型。

{ "type": "integer" }
  • number

        number 类型可用于任何数字类型,整数或浮点数。在 Python 中,类似于 float 类型。

{ "type": "number" }
  • Multiples

        multipleOf 关键字可以将数字限制为给定数字的倍数。可以将其设置为任何正数。

{
    "type"       : "number",
    "multipleOf" : 10
}
  • Range

        数字范围是使用 minimum 与 maximum 关键字(或 exclusiveMinimum 和 exclusiveMaximum 用于表示互斥范围)的组合来指定的 。

如果 x 是要验证的值,则以下条件必须为 true:

  • X ≥ minimum
  • x > exclusiveMinimum
  • X ≤ maximum
  • x < exclusiveMaximum

虽然我们可以同时指定的 minimum 和 exclusiveMinimum 或两者的 maximum 和 exclusiveMaximum,它并没有真正意义的做到这一点。

{
  "type": "number",
  "minimum": 0,
  "exclusiveMaximum": 100
}
// 取值:0-99 排除 100

3.4   对象

对象是 JSON 中的映射类型。他们将“键”映射到“值”。在 JSON 中,“键”必须始终为字符串。这些对中的每对通常都称为“属性”。

在 Python 中,“对象”类似于 dict 类型。但是,一个重要的区别是,尽管 Python 词典可以使用任何不可变对象作为键,但在 JSON 中,所有键都必须是字符串。

尽量不要被“对象”一词的两种用法所混淆:Python 使用该词 object 来表示所有事物的通用基类,而在 JSON 中,它仅用于表示从字符串键到值的映射。

{ "type": "object" }
// 类型为字典,key 为字符串
  • 属性

        properties 关键字定义对象上的属性(键值对)的值是一个对象,其中每个键是属性的名称,每个值是用于验证该属性的 JSON 模式。

例如,假设我们要为由数字,街道名称和街道类型组成的地址定义一个简单的模式:

{
  "type": "object",
  "properties": {
    "街道": { "type": "string" },
    "楼号": { "type": "number" }
  }
}
// 成功:{ "街道": "新安街道", "楼号": 123 }、{ "街道": "新安街道", "楼号": 123, "区": "宝安区"}
// 失败:{ "街道": "新安街道", "楼号": "123" }

        additionalProperties 关键字用于控制的额外的东西,默认情况下,允许任何其他属性。如果 additionalProperties 为 boolean 并将其设置为 false,则不允许使用其他属性。 

{
  "type": "object",
  "properties": {
    "街道": { "type": "string" },
    "楼号": { "type": "number" }
  },
  "additionalProperties": false
}
// 成功:{ "街道": "新安街道", "楼号": 123 }
// 失败:{ "街道": "新安街道", "楼号": "123" }、{ "街道": "新安街道", "楼号": 123, "区": "宝安区"}
  • 必须的属性

       required 关键字可以指定必须存在的属性。

{
  "type": "object",
  "properties": {
    "姓名": { "type": "string" },
    "街道": { "type": "string" },
    "楼号": { "type": "number" }
  },
  "required": ["姓名", "街道"]
}
// 成功:{ "姓名": "张三", "街道": "新安街道" }、{ "姓名": "张三", "街道": "新安街道", "楼号": 123, "区": "宝安区"}
// 失败:{ "街道": "新安街道", "楼号": "123" }
  • 属性数量

        minProperties 和 maxProperties 关键字限制对象上的属性数量 。每个参数都必须是非负整数。

{
"type": "object",
"minProperties": 2,
"maxProperties": 3
}
// 成功:{ "a": 0, "b": 1 }、{ "a": 0, "b": 1, "c": 2 }
// 失败:{}、{ "a": 0 }、{ "a": 0, "b": 1, "c": 2, "d": 3 }
  • 依赖

        dependencies 关键字允许基于某些特殊属性是变化的模式。

JSON 模式中有两种形式的依赖关系:

  • 属性依赖项声明如果存在给定的属性,则必须存在某些其他属性。
  • 模式依赖项声明存在给定属性时模式会更改。

比如,如果街道存在时,楼号也必须存在。

{
  "type": "object",
  "properties": {
    "姓名": { "type": "string" },
    "街道": { "type": "string" },
    "楼号": { "type": "number" }
  },
  "required": ["姓名"],
  "dependencies": {
    "街道": ["楼号"]
  }
}
// 成功:{ "姓名": "张三"}、{ "姓名": "张三", "街道": "新安街道", "楼号": 123}、{ "姓名": "张三", "楼号": 123}
// 失败:{ "姓名": "张三", "街道": "新安街道" }

当然也可以明确定义双向依赖性 

{
  "type": "object",
  "properties": {
    "姓名": { "type": "string" },
    "街道": { "type": "string" },
    "楼号": { "type": "number" }
  },
  "required": ["姓名"],
  "dependencies": {
    "街道": ["楼号"],
    "楼号": ["街道"]
  }
}
// 成功:{ "姓名": "张三"}、{ "姓名": "张三", "街道": "新安街道", "楼号": 123}
// 失败:{ "姓名": "张三", "街道": "新安街道" }、{ "姓名": "张三", "楼号": 123}
  • 模式依赖

        模式依赖项的工作方式类似于属性依赖项,但是它们不仅可以指定其他必需的属性,还可以扩展模式使其具有其他约束。

{
  "type": "object",
  "properties": {
    "姓名": { "type": "string" },
    "街道": { "type": "string" }
  },
  "required": ["姓名"],
  "dependencies": {
    "街道": {
      "properties": {
        "楼号": { "type": "number" }
      },
      "required": ["楼号"]
    }
  }
}
// 成功:{ "姓名": "张三"}、{ "姓名": "张三", "街道": "新安街道", "楼号": 123}
// 失败:{ "姓名": "张三", "街道": "新安街道" }

 3.5 数组

数组用于有序元素。在 JSON 中,数组中的每个元素都可以具有不同的类型。

JSON 中通常使用两种方式使用数组:

  • 列表验证:任意长度的序列,其中每个项目都匹配相同的模式。

  • 元组验证:固定长度的序列,其中每个项目可能具有不同的模式。在这种用法中,每个项目的索引(或位置)对于如何解释该值都是有意义的。

列表验证

定义数组中的每个项目都是一个数字:

{
  "type": "array",
  "items": {
    "type": "number"
  }
}
// 成功:[1, 2, 3, 4, 5]、[]
// 失败:[1, 2, "3", 4, 5]

 items 模式必须对数组中的每个项目都有效,但是 contains 模式仅需要针对数组中的一个或多个项目进行验证。

{
  "type": "array",
  "contains": {
    "type": "number"
  }
}
// 成功:[1, 2, 3, 4, 5]、["a", 4, "b"]
// 失败:["a", "b"]
  • 元组验证

        当数组是项目的集合时,其中每个项目具有不同的模式并且每个项目的序号索引都有意义,则元组验证很有用。

比如一个描述地理位置的元组:[街道, 经度, 维度, 朝向]

  • 街道:必须是字符串
  • 经度:必须是数字
  • 纬度:必须是数字
  • 朝向:只能是东南西北
    {
      "type": "array",
      "items" [
        {
          "type": "string"
        },
        {
          "type": "number"
        },
        {
          "type": "number"
        },
        {
          "type": "string",
          "enum": ["东", "南", "西", "北"]
        }
      ]
    }
    
  • 长度

        可以使用 minItems maxItems 关键字指定数组的长度。每个关键字的值必须为非负数。

 {
  "type": "array",
  "minItems": 2,
  "maxItems": 3
}
// 成功:[1, 2]、[1, 2, 3]
// 失败:[]、[1]、[1, 2, 3, 4]
  • 唯一

        可以确保数组中的每个项目都是唯一的。只需将 uniqueItems 关键字设置为即可 true。

{
  "type": "array",
  "uniqueItems": true
}
// 成功:[1, 2, 3, 4]、[]
// 失败:[1, 2, 3, 1]

 3.6 布尔值

布尔类型仅匹配两个特殊值:true 和 false。

{ "type": "boolean" }
// 成功:true、false
// 失败:"true"、0

 3.7 空(null)

空类型通常用于表示缺失值。当模式指定 type 时 null,它只有一个可接受的值:null。

{ "type": "null" }
// 成功:null
// 失败:false、0、""

 

 

你可能感兴趣的:(jsonschema,模式校验,json)