json 架构属性描述和“$ref”用法

Question

我正在编写一个 json 模式来验证我的 json 由 exe.The 模式产生的输出有点复杂，我已经定义了一些 "definitions" 被引用在属性中 ("$ref": "#/definitions/...)。在这里使用定义更为重要，因为我有一个定义是递归的情况。

我的架构现在运行良好，它正确验证了我的 json 输出。

现在，我正在尝试为每个属性使用 "description" 关键字正确记录模式。为了开发模式，我使用了一个以图形方式表示模式的编辑器 (XMLSpy)。它非常有用，但我遇到了一个奇怪的行为，我不知道这是编辑器的问题还是我不太明白。

这里是 json 模式的最小示例来解释我的问题：

{
 "$schema": "http://json-schema.org/draft-04/schema#",
 "type": "object",
 "properties": {
  "sourcePath": {
   "$ref": "#/definitions/Path",
   "description": "Here the description where I expected to set it"
  },
  "targetPath": {
   "$ref": "#/definitions/Path",
   "description": "Here another description where I expected to set it to that property of the same kind but whith a different use."
  }
 },
 "additionalProperties": false,
 "definitions": {
  "Path": {
   "description": "Here the descriptiond where it is set by the software",
   "type": "object",
   "properties": {
    "aUsefulProperty": {
     "type": "string"
    },
    "parentPath": {
     "$ref": "#/definitions/Path",
     "description": "Here yest another description where I expected to set it.."
    }
   },
   "required": [
    "aUsefulProperty"
   ],
   "additionalProperties": false
  }
 }
}

当我尝试向属性添加描述时，编辑器实际上在对象的定义中添加了描述。因此，编辑器会为属性 "sourcePath" 和 "targetPath" 显示此描述，此外还会在 "parentPath".

中显示此描述

我的意图是对每个属性进行三种不同的描述（可能还有定义本身，但这不是这里的问题）。如果我手动将它们添加到 json 模式，没有问题，但这些描述不会出现在图形编辑器中。

所以，我很困惑。

您认为这是我的图形编辑器的问题还是我错了？

基本上，当我们使用“$ref”来定义一个属性时，是否可以添加一些其他字段作为描述，或者使用“$ref”是否意味着不使用任何其他内容？在那种情况下，我怎样才能正确记录属性?

我必须向一些合作伙伴提供我的 json 模式，他们必须将它们用作文档以生成正确的 json 输出。因此，我想尽可能地向他们提供一个自我记录的 json 模式，就像我们可以用 XML.

做的那样

谢谢

Answer 1

Any members other than "$ref" in a JSON Reference object SHALL be ignored.

https://datatracker.ietf.org/doc/html/draft-pbryan-zyp-json-ref-03#section-3

为了设置 description，您必须执行类似于以下示例的操作。这可能会导致您的编辑器出现其他问题，但我很确定这是最干净的方法。

原文：

{
    "$ref": "#/definitions/Path",
    "description": "Here the description where I expected to set it"
}

建议更正：

{
    "allOf": [{ "$ref": "#/definitions/Path" }],
    "description": "Here the description where I expected to set it"
}

Answer 2

当前 JSON 架构草案允许覆盖 $refs 中的关键字。原始问题中的架构将被视为有效（取决于草案...）

来自原文Post

    ...
    "properties": {
        "sourcePath": {
            "$ref": "#/definitions/Path",
            "description": "Here the description where I expected to set it"
        },
        "targetPath": {
            "$ref": "#/definitions/Path",
            "description": "Here another description where I expected to set it to that property of the same kind but whith a different use."
        }
    },
   ...

JSON 架构规范包括 identical example:

来自 JSON 架构草案 2019

            ....
            "properties": {
                "enabled": {
                    "description": "If set to null, Feature B
                                    inherits the enabled
                                    value from Feature A",
                    "$ref": "#/$defs/enabledToggle"
                }
            }
            ...

问题中的用例正是 JSON 架构规范所描述的。事实上，您可以覆盖任何注释关键字（即 title、description、default、examples）。上面链接的示例还显示了覆盖 "default" 属性.

不幸的是，标准使实现这个成为可选的。

Applications MAY make decisions on which of multiple annotation values to use based on the schema location that contributed the value. This is intended to a allow flexible usage.

所以你应该在依赖它之前测试它。

json 架构属性描述和“$ref”用法

json schema property description and "$ref" usage

json

jsonschema

json-schema-validator

json-ref

来自原文Post

来自 JSON 架构草案 2019

json 架构 属性 描述和“$ref”用法

json schema property description and "$ref" usage

json

jsonschema

json-schema-validator

json-ref

来自原文Post

来自 JSON 架构草案 2019

json 架构属性描述和“$ref”用法