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

Question

我正在编写一个json模式来验证由exe生成的json输出.模式有点复杂,我定义了一些在属性中引用的"定义"("$ 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

应忽略JSON Reference对象中除"$ ref"以外的任何成员.

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

要设置a 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

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

来自原始帖子

    ...
    "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 Schema 规范包含一个相同的示例：

来自 JSON Schema Draft2019

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

问题中的用例正是 JSON Schema 规范所描述的。事实上，你可以覆盖任何注释的关键字（即title，description，default，examples）。上面链接的示例还显示了覆盖“默认”属性。

不幸的是，该标准使实现这一点成为可选项。

应用程序可以根据贡献值的模式位置决定使用多个注释值中的哪一个。这是为了允许灵活使用。

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