17

我正在编写一个 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 所做的那样。

谢谢

4

2 回答 2

13

JSON 引用对象中除 "$ref" 之外的任何成员都应被忽略。

为了设置 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"
}
于 2015-11-12T01:38:03.327 回答
7

$ref当前 JSON Schema 草案允许覆盖 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）。上面链接的示例还显示了覆盖“默认”属性。defaultexamples

不幸的是，该标准使实施此选项成为可选。

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

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

于 2019-11-12T04:57:01.990 回答