• 介绍
• 启动纲要
• 定义属性
• 深入了解物业
• 嵌套数据结构
• 纲要之外的引用
• 查看我们定义的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】