Я пишу схему json для проверки моих выходных данных json, созданных exe. Схема немного сложна, я определил некоторые "определения", на которые есть ссылки в свойствах ("$ 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.
Спасибо
