我可以在第三个中组合两个 JSON 模式吗？答案

【问题标题】：Can I compose two JSON Schemas in a third one?我可以在第三个中组合两个 JSON 模式吗？
【发布时间】：2021-01-07 15:04:25
【问题描述】：

我想描述我的 API 将使用 JSON Schema 返回的 JSON，并引用我的 OpenAPI 配置文件中的模式。

我需要为每个 API 方法设置不同的架构。假设我支持GET /people 和GET /people/{id}。我知道如何定义一个“人”的模式一次，并在/people 和/people/{id} 中使用$ref 引用它。

[编辑：在帖子末尾看到一个（希望）更清晰的示例]

我不明白的是如何定义和重用我的响应的结构，即：

{
   "success": true,
   "result" : [results]
}

or

{
   "success": false,
   "message": [string]
}

使用anyOf（用于成功/错误格式检查和结果，引用各种模式（people-multi.json，people-single.json），我可以定义一个“根模式”api-response.json，我可以检查 JSON 响应的一般有效性，但它不允许我检查 /people 调用是否返回一个人数组而不是一个人，例如。

如何定义一个包含响应的一般结构的api-method-people.json（当然是来自外部架构，以保持其干燥）并在result 中注入另一个架构？

编辑：一个更具体的例子（希望以更清晰的方式呈现）

我有两个 JSON 模式来描述我的两个 API 方法的响应格式：method-1.json 和 method-2.json。

我可以这样定义它们（这里不是模式，我太懒了）：

method-1.json：

{
  success: (boolean),
  result: { id: (integer), name: (string) }
}

method-2.json：

{
  success: (boolean),
  result: [ (integer), (integer), ... ]
}

但我不想重复结构（JSON 的第一级），所以我想在 response-base.json 中提取它，这将在 method-1.json 和 method-2.json 中以某种方式（？）引用，而不是为每个方法定义成功和结果属性。

简而言之，我想我想要某种组合或继承，而不是包含（$ref 允许）。

【问题讨论】：

您将再次使用 $ref 引用，但在您使用的工具中的确切工作方式可能会有所不同。
注意，在 OpenAPI 3.1 之前（目前在 RC 中），您不能使用纯 JSON Schema，而是使用 OAI 定义的 JSON Schema 的子集。从 3.1 开始，您可以使用 FULL JSON Schema，这有望使这变得更容易......但当然，您现在正在寻找解决方案，而不是 3 个月的时间。
这与我使用的工具有什么关系？在我看来，要么 JSON Schema 规范定义了一种方法来做到这一点，要么它没有……对吧？
虽然 JSON Schema 确实支持这一点，但在 OpenAPI 3.1 之前，JSON Schema 已经完全被使用了。一些 OpenAPI 工具可能支持引用外部文件，有些可能不支持，AFAIK 这样做并没有在 OpenAPI 规范本身中定义。您必须查看工具文档。
好的，很高兴知道！你能给我一些关于 JSON Schema 如何支持这一点的指示吗？即使我使用的工具不支持它。我只是不知道如何定义一个api-call-people.json 模式，基本上说“api-call-base.json 和people.json 在result 字段中。”我在文档中找不到。

标签： jsonschema openapi

【解决方案1】：

因此 JSON Schema 不允许这种组合，至少以简单的方式或在 2019-09 草案之前（感谢@Relequestual！）。

但是，我设法使它适用于我的情况。我首先在两个基本模式api-result.json 和api-error.json 中分离了两个主要情况（“结果”与“错误”）。（如果我想返回错误，我只需指向api-error.json 架构。）

在正确的 API 结果的情况下，我使用 allOf 和 $ref 为给定的操作定义一个架构以扩展基本结果架构，然后重新定义 result 属性：

{
  "$schema: "…",
  "$id": "…/api-result-get-people.json",
  "allOf": [{ "$ref": "api-result.json" }],
  "properties": {
    "result": {
       …
    }
  }
}

（编辑：我之前只在顶层使用$ref，但它似乎不起作用）

这样我可以指向这个api-result-get-people.json，并检查一般结构（success 键，值为true，以及必需的result 键）以及结果的具体形式这种“获取人员”API 方法。

【讨论】：