json schema属性描述和 "$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”是否意味着不使用其他任何内容？在这种情况下，我如何正确记录属性(property)？

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

谢谢

Answer 1

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

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

为了设置描述，您必须执行类似于以下示例的操作。它可能会导致您的编辑器出现其他奇怪的情况，但我很确定这是最简洁的方法。

原文:

{
    "$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"
}