- 介绍
- 启动纲要
- 定义属性
- 深入了解物业
- 嵌套数据结构
- 纲要之外的引用
- 查看我们定义的JSON模式的数据
介绍
下面的例子并不是JSON模式所能提供的所有值的最终结果。为此,您需要深入了解规范本身–请访问http://json-schema.org/specification.html。
假设我们正在与基于JSON的产品目录交互。此目录中的产品具有:
标识符:productId
产品名称:productName
消费者的销售成本:price
一组可选的标记:tags。
例如:
{
"productId": 1,
"productName": "A green door",
"price": 12.50,
"tags": [ "home", "green" ]
}
虽然通常很简单,但是这个例子留下了一些开放的问题。以下是其中的一些:
- 什么是productId?
- 是否需要productName?
- 价格能为零吗?
- 所有的标签都是字符串值吗?
当你谈论一种数据格式时,你想知道什么是键的元数据,包括那些键的有效输入。JSON模式是一个被提议的IETF标准,如何回答这些数据问题。
启动模型(Schema)
要开始一个模式定义,让我们从一个基本的JSON模式开始。
我们从四个名为keywords的属性开始,这些属性表示为JSON键。
对。该标准使用JSON数据文档来描述数据文档,大多数情况下这些文档也是JSON数据文档,但可以是任何数量的其他内容类型,如text/xml。
- $schema关键字指出,该模式是根据标准的特定草案编写的,并用于各种原因,主要是版本控制。
- $id关键字定义纲要的URI,以及解析纲要中其他URI引用的基URI。
- title和description注释关键字仅具有描述性。它们不会向正在验证的数据添加约束。模式的意图用这两个关键字来表述。
- type validation关键字定义了JSON数据的第一个约束,在本例中它必须是JSON对象。
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "http://example.com/product.schema.json",
"title": "Product",
"description": "A product in the catalog",
"type": "object"
}
在启动模式时,我们引入以下术语:
- Schema关键字:$Schema和$id。
- 纲要注释:标题和描述。
- 验证关键字:类型。
定义属性
productId是唯一标识产品的数值。因为这是产品的规范标识符,所以没有标识符的产品是没有意义的,所以它是必需的。
在JSON模式中,我们添加了以下内容:
properties
验证关键字。- productId 键。
- 说明模式description和type验证关键字已经注意到了–我们在上一节中讨论了这两个问题。
- 列出productId
required
的验证关键字。
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "http://example.com/product.schema.json",
"title": "Product",
"description": "A product from Acme's catalog",
"type": "object",
"properties": {
"productId": {
"description": "The unique identifier for a product",
"type": "integer"
}
},
"required": [ "productId" ]
}
- productName是描述产品的字符串值。因为没有名字的产品没什么大不了的,所以它也是必需的。
- 由于
required
的验证关键字是一个字符串数组,因此我们可以根据需要记录多个键;我们现在包括productName。 - productId和productName之间并没有什么区别,我们把两者都包括进来是为了完整性,因为计算机通常关注标识符,而人类通常关注名称。
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "http://example.com/product.schema.json",
"title": "Product",
"description": "A product from Acme's catalog",
"type": "object",
"properties": {
"productId": {
"description": "The unique identifier for a product",
"type": "integer"
},
"productName": {
"description": "Name of the product",
"type": "string"
}
},
"required": [ "productId", "productName" ]
}
深入了解properties
据店主说,没有免费的产品。;)
- price键添加了前面介绍的常用描述模式注释和类型验证关键字。它也包含在由所需验证关键字定义的键数组中。
- 我们使用exclusiveMinimum验证关键字指定price的值必须不是零。
- 如果我们想包含零作为有效价格,我们会指定
minimum
验证关键字。
- 如果我们想包含零作为有效价格,我们会指定
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "http://example.com/product.schema.json",
"title": "Product",
"description": "A product from Acme's catalog",
"type": "object",
"properties": {
"productId": {
"description": "The unique identifier for a product",
"type": "integer"
},
"productName": {
"description": "Name of the product",
"type": "string"
},
"price": {
"description": "The price of the product",
"type": "number",
"exclusiveMinimum": 0
}
},
"required": [ "productId", "productName", "price" ]
}
接下来,我们来看看标签键。
店主这样说:
如果有标记,则必须至少有一个标记,
所有标签必须是唯一的;在一个产品中不能重复。
所有标记必须为文本。
标签很好,但不需要出现。
因此:
tags键添加了常用的注释和关键字。
这次的类型验证关键字是array。
我们引入items validation关键字,以便定义数组中显示的内容。在本例中:通过类型验证关键字的字符串值。
minItems validation关键字用于确保数组中至少有一个项。
uniqueItems validation关键字说明数组中的所有项都必须彼此唯一。
我们没有将此键添加到
required的验证关键字数组中,因为它是可选的。
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "http://example.com/product.schema.json",
"title": "Product",
"description": "A product from Acme's catalog",
"type": "object",
"properties": {
"productId": {
"description": "The unique identifier for a product",
"type": "integer"
},
"productName": {
"description": "Name of the product",
"type": "string"
},
"price": {
"description": "The price of the product",
"type": "number",
"exclusiveMinimum": 0
},
"tags": {
"description": "Tags for the product",
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"uniqueItems": true
}
},
"required": [ "productId", "productName", "price" ]
}
嵌套数据结构
到目前为止,我们一直在处理一个非常扁平的模式——只有一个级别。本节演示嵌套数据结构。
dimensions键是使用我们之前发现的概念添加的。因为type validation关键字是object,所以我们可以使用properties validation关键字来定义嵌套的数据结构。
为了简洁起见,我们省略了description注释关键字。虽然在这种情况下,最好是对结构和键名进行彻底的注释,但大多数开发人员都非常熟悉它。
您将注意到所需验证关键字的范围适用于维度键,而不是超出范围。
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "http://example.com/product.schema.json",
"title": "Product",
"description": "A product from Acme's catalog",
"type": "object",
"properties": {
"productId": {
"description": "The unique identifier for a product",
"type": "integer"
},
"productName": {
"description": "Name of the product",
"type": "string"
},
"price": {
"description": "The price of the product",
"type": "number",
"exclusiveMinimum": 0
},
"tags": {
"description": "Tags for the product",
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"uniqueItems": true
},
"dimensions": {
"type": "object",
"properties": {
"length": {
"type": "number"
},
"width": {
"type": "number"
},
"height": {
"type": "number"
}
},
"required": [ "length", "width", "height" ]
}
},
"required": [ "productId", "productName", "price" ]
}
纲要之外的引用
到目前为止,我们的JSON模式是完全自包含的。为了重用、可读性和可维护性等原因,在许多数据结构中共享JSON模式是非常常见的。
在本例中,我们引入了一个新的JSON模式资源,并针对其中的两个属性:
我们使用前面提到的最小验证关键字。
我们添加了maximum validation关键字。
综合起来,这给了我们一个在验证中使用的范围。
{
"$id": "https://example.com/geographical-location.schema.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Longitude and Latitude",
"description": "A geographical coordinate on a planet (most commonly Earth).",
"required": [ "latitude", "longitude" ],
"type": "object",
"properties": {
"latitude": {
"type": "number",
"minimum": -90,
"maximum": 90
},
"longitude": {
"type": "number",
"minimum": -180,
"maximum": 180
}
}
}
接下来,我们添加对这个新模式的引用,以便可以合并它。
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "http://example.com/product.schema.json",
"title": "Product",
"description": "A product from Acme's catalog",
"type": "object",
"properties": {
"productId": {
"description": "The unique identifier for a product",
"type": "integer"
},
"productName": {
"description": "Name of the product",
"type": "string"
},
"price": {
"description": "The price of the product",
"type": "number",
"exclusiveMinimum": 0
},
"tags": {
"description": "Tags for the product",
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"uniqueItems": true
},
"dimensions": {
"type": "object",
"properties": {
"length": {
"type": "number"
},
"width": {
"type": "number"
},
"height": {
"type": "number"
}
},
"required": [ "length", "width", "height" ]
},
"warehouseLocation": {
"description": "Coordinates of the warehouse where the product is located.",
"$ref": "https://example.com/geographical-location.schema.json"
}
},
"required": [ "productId", "productName", "price" ]
}
查看我们定义的JSON模式的数据
从最早的示例数据(滚动到顶部)以来,我们肯定已经扩展了产品的概念。让我们看看与我们定义的JSON模式匹配的数据。
{
"productId": 1,
"productName": "An ice sculpture",
"price": 12.50,
"tags": [ "cold", "ice" ],
"dimensions": {
"length": 7.0,
"width": 12.0,
"height": 9.5
},
"warehouseLocation": {
"latitude": -78.75,
"longitude": 20.4
}
}
原文:https://json-schema.org/learn/getting-started-step-by-step.html
本文:http://jiagoushi.pro/node/1096
讨论:请加入知识星球【首席架构师圈】或者小号【jiagoushi_pro】
最新内容
- 3 hours ago
- 3 hours ago
- 3 days 4 hours ago
- 3 days 17 hours ago
- 5 days 4 hours ago
- 5 days 22 hours ago
- 5 days 22 hours ago
- 5 days 22 hours ago
- 5 days 22 hours ago
- 5 days 22 hours ago