openapi - 为什么 OpenAPI 不将 '$ref' 定义为允许的属性？

Question

与 draft-07 相比，它定义了:

{
    "type": ["object", "boolean"],
    "properties": {
        ...
        "$ref": {
            "type": "string",
            "format": "uri-reference"
        },
    }
    ...
}

目前我正在尝试为 openapi 编写验证程序.但验证失败，因为 openapi schema (是的，它是来自 google api 的模式)没有将 $ref 定义为 schema 的允许属性。

这是错字吗？关于如何检查 $ref 属性的建议是什么？

Answer 1

$ref 是一个 JSON 引用。它不是 schema 定义的一部分，而是 reference 的一部分定义:

"reference": {
  "type": "object",
  "description": "A simple object to allow referencing other components in the specification, internally and externally.  The Reference Object is defined by JSON Reference and follows the same structure, behavior and rules.   For this specification, reference resolution is accomplished as defined by the JSON Reference specification and not by the JSON Schema specification.",
  "required": [
    "$ref"
  ],
  "additionalProperties": false,
  "properties": {
    "$ref": {
      "type": "string"
    }
  }
},

然后其他允许使用 $ref 的定义使用 oneOf something 或 reference ( example ) :

"schemaOrReference": {
  "oneOf": [
    {
      "$ref": "#/definitions/schema"
    },
    {
      "$ref": "#/definitions/reference"
    }
  ]
},

顺便说一句，官方 OpenAPI 规范存储库中目前有两种不同的 OAS3 JSON 模式草案。请随意尝试，并在相应的讨论中提供您的反馈。

• [WIP] Alternative OAS3 JSON Schema ( link to schema )
• OpenAPI v3 JSON Schema ( link to schema )