JSON Schema 参考书

本文作者:IMWeb 孙世吉 原文出处:IMWeb社区 未经同意,禁止转载

1 简介

JSON 模式(JSON Schema)是一种基于 JSON 格式定义 JSON 数据结构的规范。其用于:

  • 描述现有数据格式。
  • 干净的人类和机器可读的文档。
  • 完整的结构验证,有利于自动化测试,可用于验证客户端提交的数据。

表现形式上来说 JSON Schema实际上也还是JSON数据。 JSON Schema制定了一系列规范,使得我们可以使用它来定义JSON数据的格式。

这有点像我们先定义了“语言”是什么怎么用,然后可以用“语言”来规定什么是诗词歌赋。“诗词歌赋”以及“诗词歌赋的定义”实际上也都还是“语言”。

简单来说,我们有JSON数据①,我们可以定义JSON数据②用来描述①的结构。这时候JSON数据②也就是JSON Schema,它可以描述以及验证JSON数据①。

JSON数据①:

{
    "name": "shijisun",
    "age": 24,
    "gender": "male"
}

JSON数据②(JSON Schema):

{
    "type": "object",
    "properties": {
        "name": {
            "type": "string",
            "minLength": 4
        },
        "age": {
            "type": "integer",
            "minimum": 0,
            "maximum": 130
        },
        "gender": {
            "type": "string",
            "enum": [
                "male",
                "female"
            ]
        }
    }
}

如上所示,JSON数据②描述JSON数据①: 1、是一个json对象,有三个属性:name、age和gender; 2、name属性的值是一个字符串,最小长度4; 3、age属性的值是一个整形数,最小值0.最大值130; 4、gender属性的值是一个字符串,只能取“male”或者“female”

2 基础

JSON数据有两种结构:objectarray

而object和array中的value可以取到如下几种类型的值。

本节说明怎么使用Schema描述上述类型与结构。

2.1 基本类型

JSON Schema为json值定义了7种基本类型,基本与JSON定义一致:

类型

描述

boolean

A JSON boolean.

integer

A JSON number without a fraction or exponent part.

number

Any JSON number. Number includes integer.

string

A JSON string.

object

A JSON object.

array

A JSON array.

null

The JSON null value.

2.2 schema定义

2.2.1 定义Schema实例

一个最简单的JSON Schema实例:

{
    "type": SchemaType
}

其中SchemaType是JSON Schema支持的基本类型,例如 "boolean"。

2.2.2 定义非嵌套类型

使用Schema定义一个类型为booleanintegernumberstringnull的json数据。 Schema:

{
    "type": "integer"
}

示例数据:

12345

上面描述了一个值为整型数的json数据,同理只要使用2.1说明的其他类型替换type字段的内容即可用于定义其他类型。

2.2.3 定义嵌套类型

2.2.3.1 object

  • 类型为object的Schema,通过properties属性声明键值对中key的值value的类型

Schema:

{
    "type": "object",
    "properties": {
        "id": {
            "type": "integer"
        },
        "name": {
            "type": "string"
        },
        "age": {
            "type": "integer"
        },
        "gender": {
            "type": "string"
        }
    }
}

示例数据:

{
    "id": 12345,
    "name": "shijisun",
    "age": 24,
    "gender": "male"
}

例如:在上述例子中,定义object下有一个值为integer类型的属性“id”

2.2.3.2 array

  • 类型为为array的Schema,通过items属性定义列表内元素的类型

Schema:

{
    "type": "array",
    "items": {
        "type": "string"
    }
}

示例数据:

[
  "hello",
  "world",
  "!"
]

2.2.4 嵌套定义说明

如果以 {{Schema}} 表示定义的JSON Schema实例,例如2.2.3中列举的都是Schema实例。 那么JSON Schema的嵌套定义规则可以表示成下面的形式:

{
    "type": "object",
    "properties": {
        "key1": {{Schema}},
        "key2": {{Schema}}
    }
}
{
    "type": "array",
    "items": {{Schema}}
}

你会发现这与JSON的定义是一致的。

JSON的定义

JSON Schema的定义

object

type为object的 JSON Schema 实例,使用properties属性声明key值与value类型

array

type为array的 JSON Schema 实例,使用items属性声明value类型

value

任意 JSON Schema 实例

我们可以使用JSON Schema描述所有可能出现的JSON数据结构

3 进阶

在上文我们已经可以使用JSON Schema描述现有JSON数据的格式了,但是你会发现我们可以定义object里面有什么属性,各个属性是什么类型;array里面的是什么类型的数据。但是我们还未对具体的数据进行限制,例如字符串的长度,整型数的取值范围,数组的长度等。 而JSON Schema实际上也定义了这些规范,以下列举了部分JSON Schema定义的用于数据验证的关键字。

注:下面的描述中,跟Schema有效性相关的实例一般指JSON Schema实例,与json数据验证相关的实例一般指JSON数据实例。

3.1 元数据关键字

关键字

描述

Schema有效值

用途

title

标题

字符串

描述信息

description

描述

字符串

更加详尽的描述信息

default

默认值

无限制

定义默认值

3.2 通用验证关键字

关键字

描述

Schema有效值

json数据验证

enum

数据枚举

必须是数组,而且数组里面的元素至少必须有一个而且不能有重复值。

当json实例的值存在于enum列表中时,通过验证

type

定义类型

可以是字符串或者字符串数组,取值必须在Schema基本类型范围内

allOf

数据验证

必须是object Schema实例数组,而且数组里面的元素至少必须有一个而且不能有重复

JSON实例满足其中所有的Schema时,通过验证

anyOf

数据验证

同allOf

JSON实例满足其中某一个Schema时,通过验证

oneOf

数据验证

同allOf

JSON实例刚好只满足其中某一个Schema时,通过验证

not

数据验证

必须是一个object,而且是个有效的JSON Schema

如果不满足JSON Schema的定义,则通过验证

definitions

定义子模式

必须是一个object,object下所有属性的值都必须是有效的JSON Schema

用于定义子模式

3.3 跟类型相关的关键字

3.3.1 数字

关键字

描述

Schema有效值

json数据验证

multipleOf

整数倍

大于0的JSON数

当JSON实例的值是其整数倍的时候,通过验证

maximum

最大值

一个JSON数

当JSON实例的值小于等于maximum的时候,通过验证

exclusiveMaximum

包含最大值

布尔值,必须与maximum一起使用

当其为true的时候,JSON实例不能等于maximum的值

minimum

最小值

一个JSON数

当JSON实例的值大于等于minimum的时候,通过验证

exclusiveMinimum

包含最小值

布尔值,必须与minimum一起使用

当其为true的时候,JSON实例不能等于minimum的值

以上关键字同时适用于integer和number

3.3.2 字符串

关键字

描述

Schema有效值

json数据验证

maxLength

最大长度

大于等于0的整数

字符串的长度必须小于等于该值

minLength

最小长度

大于等于0的整数

字符串的长度必须大于等于该值

pattern

模式

字符串,必须是有效的正则表达式

当字符串符合正则表达式时,通过验证

3.3.3 数组

关键字

描述

Schema有效值

json数据验证

items

定义元素

必须是object或者array的Schema实例,如果是array则其元素也必须是object

用于定义array中的元素类型

additionalItems

长度限制

布尔值或类型为object的Schema实例

当items为array,additionalItems为false时,json数据长度必须小于等于items长度

maxItems

长度限制

大于等于的整数

array实例的长度必须小于等于maxItems的值

minItems

长度限制

大于等于的整数

array实例的长度必须大于等于minItems的值

uniqueItems

唯一值

布尔值,默认值false

当uniqueItems为true的时候,array实例不能有重复值。

3.3.4 对象

关键字

描述

Schema有效值

json数据验证

properties

属性

object,属性的值必须都是有效的Schema实例

用于定义属性列表

maxProperties

最大属性个数

大于等于的整数

object实例的属性个数必须小于等于maxProperties的值

minProperties

最小属性个数

大于等于的整数

object实例的属性个数必须大于等于minProperties的值

required

必须属性

字符串数组,至少必须有一个元素,数组内不能有重复值

object实例必须有所有required定义的属性

dependencies

定义依赖

object,属性对应的值必须是object或者字符串数组。

-

dependencies中定义的(name, schema) 模式依赖:name对应的JSON值必须也满足schema的定义; dependencies中定义的(name, propertyset) 属性依赖:如果JSON实例拥有对应的属性名name,则也必须有name对应的propertyset数组内的所有属性名。

3.4 语义有效性

单独的结构验证可能不足以验证一个实例是否满足应用程序的所有要求。 format关键字对值的固定子集进行可互操作的语义验证。 这些子集已经被权威机构进行准确的描述,例如data-timemailhostnameipv4等。

4 更多

官方网站 生成JSON Schema在线工具 Schema验证JSON数据在线工具

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

发表于

我来说两句

0 条评论
登录 后参与评论

相关文章

来自专栏landv

Java基本语法

1611
来自专栏Python爬虫实战

Python指南:组合数据类型

Python提供了5中内置的序列类型:bytearray、bytes、list、str与tuple,序列类型支持成员关系操作符(in)、大小计算函数(len()...

1531
来自专栏java学习

面试題5(请说出Java 语言中覆盖和重事)

考点:考察求职者对于Java重载和覆盖的区分。 出现频率: ★★★ 【面试题解析】考察求职者对于Java 重载和覆盖的区分。从前面对重载和覆盖的描述,很容易就能...

2928
来自专栏老九学堂

10分钟,掌握90%的人都不会的指针算术结构!

上例中,一般而言数组名array 代表数组本身,类型是int[10],但如果把array 看做指针的话,它指向数组的第0 个单元,类型是int* 所指向的类型是...

1021
来自专栏python学习之旅

Python笔记(九):字符串操作

(一)    字符串 单引号、双引号、三重引号都可以作为字符串的开始和结束,三重引号可以直接输入多行字符串。三重引号可能一般是用来写多行注释。 ? (二)   ...

3997
来自专栏全沾开发(huā)

数组的遍历你都会用了,那Promise版本的呢

2784
来自专栏前端真相

JavaScript基础(3)

1945
来自专栏土豆专栏

Java面试之数据类型(一)

封装类是引用类型,基本类型在传递参数的时候都是按值传递,而封装类型是按引用传递的(其实引用也是按值传递的,但是传递的是对象的地址)

1842
来自专栏前端知识分享

第191天:js---Array常用属性和方法总结

1242
来自专栏武军超python专栏

python组合数据类型及各种操作小总结

python中,一共有四种组合数据类型,他们分别是列表(list),元组(tuple),集合(set),字典(dict)。而这些数据类型分别都有什么作用?他们有...

1227

扫码关注云+社区

领取腾讯云代金券