dictionary - Почему `AdditionalProperties` является способом представления словаря/карты в Swagger/OpenAPI 2.0




hash mapping (2)

Во-первых, я нашел лучшее объяснение additionalProperties :

Для объекта, если он указан, в дополнение к свойствам, определенным в properties , разрешены все другие имена свойств. Их значения должны соответствовать объекту схемы, указанному здесь. Если это не дано, никакие другие свойства, кроме определенных в properties не допускаются.

Вот как я наконец понял это:

Используя properties , мы можем определить известный набор свойств, похожих на namedtuple Python , однако, если мы хотим иметь что-то более похожее на dict Python или любой другой хэш / карту, где мы не можем указать, сколько ключей есть, и в чем они находятся заранее, мы должны использовать additionalProperties .

additionalProperties будет соответствовать любому имени свойства (которое будет действовать как ключ dict , а $ref или type будет схемой значения dict , и поскольку не должно быть более одного свойства с одинаковым именем для каждого По заданному объекту мы получим принудительное применение уникальных ключей.

Обратите внимание, что в отличие от слова Python, которое принимает любое неизменяемое значение в качестве ключа, поскольку ключи здесь, по сути, являются именами свойств, они должны быть строками. (Спасибо Теду Эпштейну за это разъяснение). Это ограничение можно отследить до pair := string : value в спецификации json .

Хотя я видел примеры в спецификации OpenAPI :

type: object
additionalProperties:
  $ref: '#/definitions/ComplexModel'

для меня не очевидно, почему использование additionalProperties является правильной схемой для карты / словаря.

Также не помогает, что единственная конкретная вещь, которую спецификация должна сказать о additionalProperties свойствах:

Следующие свойства взяты из определения схемы JSON, но их определения были адаптированы к спецификации Swagger. Их определение совпадает с определением из схемы JSON, но только если исходное определение ссылается на определение схемы JSON, вместо этого используется определение объекта схемы.

  • Предметы
  • все
  • свойства
  • additionalProperties

Чен, я думаю, что ваш ответ правильный.

Некоторые дополнительные сведения, которые могут быть полезны:

В JavaScript, который был исходным контекстом для JSON, объект подобен хэш-карте строк в значения, где одни значения являются данными, другие - функциями. Вы можете рассматривать каждую пару имя-значение как свойство. Но в JavaScript нет классов, поэтому имена свойств не определены заранее, и у каждого объекта может быть свой независимый набор свойств.

Схема JSON использует ключевое слово properties для проверки заранее известных пар имя-значение; и использует additionalProperties patternProperties (или patternProperties , не поддерживаемые в OpenAPI 2.0) для проверки свойств, которые не известны.

Для ясности:

  • Имена свойств или «ключи» на карте должны быть строками. Они не могут быть числами или любым другим значением.
  • Как вы сказали, имена свойств должны быть уникальными. К сожалению, спецификация JSON не требует строго уникальности, но уникальность рекомендуется и ожидается большинством реализаций JSON. Больше фона here .
  • properties и additionalProperties properties могут быть использованы отдельно или в комбинации. Когда AdditionalProperties используется один, без свойств, объект по существу функционирует как map<string, T> где T - тип, описанный в подсхеме AdditionalProperties. Может быть, это поможет ответить на ваш оригинальный вопрос.
  • При оценке объекта по одной схеме, если имя свойства совпадает с одним из указанных в properties , его значение должно быть действительным только для подсхемы, предоставленной для этого свойства. Подсхема AdditionalProperties, если она предусмотрена, будет использоваться только для проверки свойств, которые не включены в карту properties .
  • Существуют некоторые ограничения additionalProperties свойств, реализованных в основных библиотеках Java Swagger. Я задокументировал эти ограничения here .




openapi