json - 是否有推荐的方法来构造多个 JSON 模式？

Question

我刚刚编写了我的第一个 JSON 模式，太棒了!但是，我现在正在研究如何构建多个 JSON 模式，包括在开发期间以及之后如何托管它们。这方面的指导似乎非常有限。

当然，我查了json-schema.org官方文档on how to structure a complex scheme ，甚至让东西工作。我现在有三个模式，在开发过程中以文件夹结构组织如下:

json-schemas
  - /common
    - /common-schemas.json
  - /data
    - /data-schemas.json
    - /DataStreamServiceRequest
      - /DataStreamServiceRequest-schema.json

在这三个中，只有 DataStreamServiceRequest-schema.json包含一个单一 模式(它是对应用程序服务端点的所有可能请求的模式)。它指的是 data-schemas.json 中定义的类型和 common-schemas.json通过使用相对引用。此处的目的是在一个文件中提供单个子系统的所有类型(例如，data)。

我为所有三个 .json 文件分配了一个包含绝对 URI 的 $id，对应于它们所在的目录。

例如，这里是common-schemas.json:

{
  "$schema": "https://json-schema.org/draft/2019-09/schema",
  "$id": "https://carp.cachet.dk/schemas/common",
  "NamespacedId": {
    "type": "string",
    "pattern": "^([a-z_0-9]+\\.?)+[a-z_0-9]$"
  }
}

并且，从 data-schemas.json 中，我引用 common-schemas.json 中的 NamespacedId 使用:

"dataType": { "$ref": "common#/NamespacedId" }

我很高兴这有效，但是，这是推荐的吗？我是否忽略了一些基本的架构结构，如下所示？是否有任何特别的理由更喜欢“每种类型一个模式”？是否有我忽略的惯用结构，例如，相当于 Java 的文件位置对应于命名空间？

如果没有(我认为在 Java 中有)那也构成一个答案。

也许还有其他相关上下文:我正在使用 networknt/json-schema-validator ，并且为了开发/测试目的，没有太多的绝对 URI 是非常方便的。我 need to map each URI to a local file在初始化验证器时。

Answer 1

正如@Ether 所说，没有唯一的正确答案，但这是我使用的指南。

最重要的指南是像对待系统中的任何其他代码一样对待您的模式。通常，这意味着您描述的每个“事物”(“人”、“产品”、“地址”等)都应该有自己的架构。

定义 ($defs) 只能在同一模式中被引用 ($ref)。使用定义来提高可读性或减少架构中的重复。任何对外部架构的引用都不应该有 JSON 指针 URI 片段(例如，您使用的 #/$defs/NamespacedId 片段)。如果您需要在外部模式中引用定义，它可能是一个标志，它应该在它自己的模式中。

如果您有一堆微小的模式要放入“common.schema.json”模式中，这可能是一个异常(exception)。在这种情况下，您的所有模式都应定义为定义，但有一个 anchor $anchor。它需要是一个定义，以便您可以使用标准工具来验证您的模式是否有效。使用 anchor 可以让您更轻松地引用它，但更重要的是，这是一个信号，表明某些外部模式可能依赖于它。没有 anchor 的定义实际上是模式私有(private)的，而带有 anchor 的定义实际上是公开的。您可以自由地重构 unanchored 定义，但如果重构锚定的定义，则必须警惕破坏其他模式。

不要使用 $id。当模式没有 $id 时，它由用于检索模式的 URI 标识。这可以是文件 URI (file:///path/to/schemas/person.schema.json)。那么您的所有引用都可以是相对的，这意味着您的架构中没有绝对 URI，并且您不需要配置来将 https URI 映射到文件位置。遗憾的是，并非所有实现都支持基于文件的检索甚至检索 URI 标识，因此这并不总是可行的。

以有意义的方式组织您的模式。遵循与任何其他代码相同的直觉和准则。如果您必须使用 $id，请确保路径与文件系统上的路径匹配(例如 https://example.com/schemas/person => file:///local/path/to/app/schemas/person.schema.json)。这只会让您更轻松地找到您正在寻找的模式。