Описание свойства json schema и использование «$ ref»

Question

Я нахожу схему json для проверки моих json-выходов, созданных exe. Схема, которая немного сложна, я определил некоторые «определения», на которые ссылаются свойства (" $ ref ":" #/определения/...). И использование определений здесь тем более важно, потому что у меня есть случай, когда определение является рекурсивным.

Моя схема теперь работает хорошо, она корректно проверяет мои json-выходы .

Теперь я пытаюсь правильно документировать схему, используя ключевое слово "description" для каждого свойства. Для разработки схемы я использую редактор (XMLSpy), который представляет схему графически. Это очень полезно, но мне кажется, behaviou r, и я не знаю, является ли это проблемой в редакторе, или я не понимаю этого.

Вот минимальный пример JSon схемы, чтобы объяснить мою проблему:

{ 
 
\t "$schema": "http://json-schema.org/draft-04/schema#", 
 
\t "type": "object", 
 
\t "properties": { 
 
\t \t "sourcePath": { 
 
\t \t \t "$ref": "#/definitions/Path", 
 
\t \t \t "description": "Here the description where I expected to set it" 
 
\t \t }, 
 
\t \t "targetPath": { 
 
\t \t \t "$ref": "#/definitions/Path", 
 
\t \t \t "description": "Here another description where I expected to set it to that property of the same kind but whith a different use." 
 
\t \t } 
 
\t }, 
 
\t "additionalProperties": false, 
 
\t "definitions": { 
 
\t \t "Path": { 
 
\t \t \t "description": "Here the descriptiond where it is set by the software", 
 
\t \t \t "type": "object", 
 
\t \t \t "properties": { 
 
\t \t \t \t "aUsefulProperty": { 
 
\t \t \t \t \t "type": "string" 
 
\t \t \t \t }, 
 
\t \t \t \t "parentPath": { 
 
\t \t \t \t \t "$ref": "#/definitions/Path", 
 
\t \t \t \t \t "description": "Here yest another description where I expected to set it.." 
 
\t \t \t \t } 
 
\t \t \t }, 
 
\t \t \t "required": [ 
 
\t \t \t \t "aUsefulProperty" 
 
\t \t \t ], 
 
\t \t \t "additionalProperties": false 
 
\t \t } 
 
\t } 
 
}

Когда я пытаюсь добавить описание свойства, редактор фактически добавить описание внутри определение объекта. В результате редактор отображает это описание как для свойств «sourcePath», так и для «targetPath», кроме того, оно отображает это описание также в «parentPath».

Мое намерение состоит в том, чтобы иметь три разных описания по одному для каждого свойства (и, возможно, также само определение, но это не проблема). Если я добавлю их вручную в json-схему, нет проблем, но эти описания не отображаются в графическом редакторе.

Итак, я смущен.

Считаете ли вы, что это проблема с моим графическим редактором или я ошибаюсь?

В принципе, когда мы используем «$ ref» для определения свойства, можно ли добавить другое поле в качестве описания, или же использование «$ ref» подразумевает не использование ничего другого? В этом случае, как я могу правильно документировать свойство?

Я должен предоставить свои json-схемы некоторым партнерам, которые должны будут использовать их в качестве документации для создания правильного выхода json. Поэтому, насколько это возможно, я хотел бы предоставить им самодокументирующую json-схему, как мы можем это сделать с XML.

Благодаря

Answer 1

Любые другие, чем "$ реф" члены в JSON справочном объект должен быть игнорироваться.

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

Для того, чтобы установить 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" 
}