17

exeによって生成されたjson出力を検証するためにjsonスキーマを書いています。スキーマは少し複雑なので、プロパティで参照されるいくつかの「定義」を定義しました(「$ref」:「#/definitions/...)」定義が再帰的である場合があるため、ここで定義を使用することはさらに重要です。

私のスキーマは正常に機能するようになり、json 出力が正しく検証されます。

現在、各プロパティの「説明」キーワ​​ードを使用して、スキーマを正しく文書化しようとしています。スキーマを作成するには、スキーマをグラフィカルに表示するエディター (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」にもこの説明を表示します。

私の意図は、プロパティごとに 1 つずつ、3 つの異なる説明を用意することです (おそらく定義自体もそうですが、ここでは問題ではありません)。json スキーマに手動で追加しても問題はありませんが、これらの説明はグラフィカル エディターに表示されません。

だから、私は混乱しています。

私のグラフィカルエディタの問題だと思いますか、それとも間違っていますか?

基本的に、「$ref」を使用してプロパティを定義する場合、説明として他のフィールドを追加することは可能ですか、それとも「$ref」を使用することは他に何も使用しないことを意味しますか? その場合、プロパティを正しく文書化するにはどうすればよいですか?

json スキーマを一部のパートナーに提供する必要があります。パートナーは、それらをドキュメントとして使用して、正しい json 出力を生成する必要があります。したがって、可能な限り、XML でできるように自己文書化された json スキーマを彼らに提供したいと思います。

ありがとう

4

2 に答える 2

13

JSON 参照オブジェクトの「$ref」以外のメンバーはすべて無視されます。

を設定する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 に答える