json模式属性说明和"$ ref"用法 [英] json schema property description and "$ref" usage
问题描述
我正在编写一个json模式来验证我由exe生成的json输出.该模式有点复杂，我定义了一些在属性中引用的定义"("$ ref":#/definitions/. ..).在这里使用定义更为重要，因为我有一个定义是递归的情况.
I am writting a json schema to validate my json outputs produced by an exe.The schema being little bit complexe, I have defined some "definitions" that are referenced in properties ("$ref": "#/definitions/...). And using definitions here is all the more important because I have a case where the definition is recursive.
我的模式现在运行良好，可以正确验证我的json输出.
My schema now works well, it validates correctly my json outputs.
现在，我正在尝试使用每个属性的"description"关键字正确记录架构.为了开发模式，我使用了以图形方式表示模式的编辑器(XMLSpy).它非常有用，但是我面临着一种奇怪的行为，我不知道这是编辑器中的问题还是我自己不太了解.
Now, I am trying to document the schema correctly using "description" keyword for each property. To develop the schema I use an editor (XMLSpy) that represents the schema graphically. It is very usefull but I face a curious behaviour and I do not know if it is a problem in the editor or if it is me that do not really understand.
这是json模式的一个最小示例来解释我的问题:
Here is a minimal example of json schema to explain my problem:
{
"$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"中显示此描述.
When I am trying to add a description to a property, the editor actually add a description inside the definition of the object. In consequence the editor displays this description for both properties "sourcePath" and "targetPath", moreover it displays this description also in "parentPath".
我的意图是为每个属性提供三个不同的描述(可能还有定义本身，但这不是问题所在).如果我将它们手动添加到json模式，则没有问题，但是这些描述不会出现在图形编辑器中.
My intent is to have three different descriptions one for each property, (and probably also the definition itself but it is not the problem here). If I add them manually to the json schema, there is no problem but these descriptions does not appear in the graphical editor.
所以，我很困惑.
您认为我的图形编辑器有问题还是我错了?
Do you think it is a problem with my graphical editor or am I wrong?
基本上，当我们使用"$ ref"来定义属性时，是否可以添加其他字段作为描述，或者使用"$ ref"是否意味着不使用其他内容?在这种情况下，如何正确记录财产?
Basically, when we use a "$ref" to define a property, is it possible to add some other field as the description or does using a "$ref" imply not using nothing else? In that case, how can I document correctly a property?
我必须将我的json模式提供给某些合作伙伴，这些合作伙伴必须将它们用作文档以产生正确的json输出.因此，我想尽可能地向他们提供我们可以使用XML进行自我记录的json模式.
I have to provide my json schemas to some partners, that will have to use them as documentation to produce correct json output. So, as far as possible, I would like to provide to them a self-documenting json schema as we can do with XML.
谢谢
推荐答案
JSON参考对象中除"$ ref"以外的任何成员都应为 忽略了.
Any members other than "$ref" in a JSON Reference object SHALL be ignored.
- https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03#section-3
要设置description，您必须执行类似以下示例的操作.这可能会导致您的编辑器出现其他怪异现象，但是我很确定这是最干净的方法.
In order to set a description, you would have to do something like the following example. It might cause other weirdness in you editor, but I'm pretty sure this is the cleanest way to do it.
原文:
{
"$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"
}
这篇关于json模式属性说明和"$ ref"用法的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！
