JSON 使用空片段的架构引用

Question

我正在使用 OpenAPI 规范并找到指向空字符串（空片段）的引用标记。这是正确的参考吗？如果是，如何解释这个参考？它指向什么，在验证 OpenAPI 规范时确定什么值是正确的？

我已经检查了 OpenAPI 草稿以及 JSON 模式草稿，但他们没有提到如何处理这个问题，也没有任何关于什么是正确行为的示例或指导。

感谢任何帮助。

下面是一个例子...注意在 Amount/Amount 下有一个 "$ref": ""

（此示例是英国开放银行模型中余额规范的一部分）

:
:
"Amount": {
  "type": "object",
  "required": [
    "Amount",
    "Currency"
  ],
  "description": "Amount of money of the cash balance.",
  "properties": {
    "Amount": {
      "$ref": ""
    },
    "Currency": {
      "$ref": "#/components/schemas/ActiveOrHistoricCurrencyCode_1"
    }
  }
}
:
:

Answer 1

您没有在任何规范中找到这一点的原因是因为它们都遵循 RFC-3986 来定义 URI 的解析方式。这意味着 JSON Schema 和 OpenAPI 中的 URI 解析与 HTML 完全相同，因此大多数 Web 开发人员应该很熟悉。 Understanding JSON Schema 站点有一个部分解释了 RFC-3986 URI 解析如何在 JSON 模式的上下文中工作。

在这种情况下，基本 URI 是文档的位置。它可能在文件系统上：file:///path/to/myapi.openapi.json，或者它可能在 Web http://example.com/myapi.openapi.json 上。在 $ref 中找到的相对引用 URI 是根据此基本 URI 解析的。解析针对基本 URI 的空相对引用会生成与基本 URI 相同的 URI。

这意味着在您的示例中，此 $ref 引用的是 OpenAPI 文档而不是 JSON 架构，这在 JSON 架构中是不允许的。 JSON 架构中的 $ref 只能引用 JSON 架构。这似乎是您正在使用的 OpenAPI 文档中的一个错误。

然而，这并不意味着空 $ref 总是无效的。在 JSON 架构文档（未嵌入 OpenAPI 文档）中，您可以使用它来定义 recursive structure。通常你会看到递归引用定义为 "$ref": "#" 而不是空的，但是没有任何好的理由包含 #。无论哪种方式，你都应该在同一个地方结束。

JSON 使用空片段的架构引用

JSON Schema reference using an empty fragment

jsonschema

openapi