前往小程序,Get更优阅读体验!
立即前往
首页
学习
活动
专区
工具
TVP
发布
社区首页 >专栏 >JSON Schema 参考书

JSON Schema 参考书

作者头像
IMWeb前端团队
发布2018-01-08 16:51:25
2K0
发布2018-01-08 16:51:25
举报
文章被收录于专栏:IMWeb前端团队

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

1 简介

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

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

表现形式上来说 JSON Schema实际上也还是JSON数据。

JSON Schema制定了一系列规范,使得我们可以使用它来定义JSON数据的格式。

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

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

JSON数据①:

代码语言:javascript
复制
{
    "name": "shijisun",
    "age": 24,
    "gender": "male"
}

JSON数据②(JSON Schema):

代码语言:javascript
复制
{
    "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实例:

代码语言:javascript
复制
{
    "type": SchemaType
}

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

2.2.2 定义非嵌套类型

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

Schema:

代码语言:javascript
复制
{
    "type": "integer"
}

示例数据:

代码语言:javascript
复制
12345

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

2.2.3 定义嵌套类型

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

Schema:

代码语言:javascript
复制
{
    "type": "object",
    "properties": {
        "id": {
            "type": "integer"
        },
        "name": {
            "type": "string"
        },
        "age": {
            "type": "integer"
        },
        "gender": {
            "type": "string"
        }
    }
}

示例数据:

代码语言:javascript
复制
{
    "id": 12345,
    "name": "shijisun",
    "age": 24,
    "gender": "male"
}

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

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

Schema:

代码语言:javascript
复制
{
    "type": "array",
    "items": {
        "type": "string"
    }
}

示例数据:

代码语言:javascript
复制
[
  "hello",
  "world",
  "!"
]

2.2.4 嵌套定义说明

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

代码语言:javascript
复制
{
    "type": "object",
    "properties": {
        "key1": {{Schema}},
        "key2": {{Schema}}
    }
}
代码语言:javascript
复制
{
    "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数据在线工具

本文参与 腾讯云自媒体同步曝光计划,分享自作者个人站点/博客。
如有侵权请联系 cloudcommunity@tencent.com 删除

本文分享自 作者个人站点/博客 前往查看

如有侵权,请联系 cloudcommunity@tencent.com 删除。

本文参与 腾讯云自媒体同步曝光计划  ,欢迎热爱写作的你一起参与!

评论
登录后参与评论
0 条评论
热度
最新
推荐阅读
目录
  • 1 简介
  • 2 基础
    • 2.1 基本类型
      • 2.2 schema定义
        • 2.2.1 定义Schema实例
        • 2.2.2 定义非嵌套类型
        • 2.2.3 定义嵌套类型
        • 2.2.4 嵌套定义说明
    • 3 进阶
      • 3.1 元数据关键字
        • 3.2 通用验证关键字
          • 3.3 跟类型相关的关键字
            • 3.3.1 数字
            • 3.3.2 字符串
            • 3.3.3 数组
            • 3.3.4 对象
          • 3.4 语义有效性
          • 4 更多
          领券
          问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档