`additionalProperties`がSwagger / OpenAPI 2.0で辞書/地図を表す方法である理由

Question

OpenAPI仕様の例を見てきましたが：

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

私には明らかではありませんなぜadditionalPropertiesの使用はMap/Dictionaryの正しいスキーマです。

また、仕様がadditionalPropertiesについて述べなければならない具体的なことは次のことだけです。

次のプロパティはJSONスキーマ定義から取得されますが、定義はSwagger仕様に合わせて調整されています。それらの定義は、JSONスキーマの定義と同じです。元の定義がJSONスキーマ定義を参照する場合のみ、代わりにスキーマオブジェクト定義が使用されます。

アイテム

すべての

物性

additionalProperties

Ted Epstein · Accepted Answer

チェン、私はあなたの答えが正しいと思います。

役に立つかもしれないさらなる背景：

JSONの元のコンテキストであったJavaScriptでは、オブジェクトは文字列から値へのハッシュマップのようなものです。一部の値はデータであり、他の値は関数です。各名前と値のペアをプロパティと考えることができます。ただし、JavaScriptにはクラスがないため、プロパティ名は事前定義されておらず、各オブジェクトは独自の独立したプロパティセットを持つことができます。

JSONスキーマはpropertiesキーワードを使用して、事前に知られている名前と値のペアを検証します。 additionalProperties（またはpatternProperties、OpenAPI 2.0ではサポートされていません）を使用して、不明なプロパティを検証します。

明確にするために：

プロパティ名、またはマップ内の「キー」は文字列でなければなりません。数字やその他の値にすることはできません。
あなたが言ったように、プロパティ名shouldは一意です。残念ながら、JSON仕様は一意性を厳密に要求しませんが、一意性が推奨され、ほとんどのJSON実装で期待されています。より多くの背景ここ。
propertiesおよびadditionalPropertiesは、単独でまたは組み合わせて使用できます。 additionalPropertiesがプロパティなしで単独で使用される場合、オブジェクトは基本的にmap<string, T>ここで、TはadditionalPropertiesサブスキーマに記述されているタイプです。元の質問に答えるのに役立つかもしれません。
単一のスキーマに対してオブジェクトを評価する場合、プロパティ名がpropertiesで指定された名前のいずれかに一致する場合、その値はそのプロパティに提供されたサブスキーマに対してのみ有効である必要があります。 additionalPropertiesサブスキーマが提供される場合、propertiesマップに含まれるではないのプロパティを検証するためにのみ使用されます。
SwaggerのコアJavaライブラリに実装されているadditionalPropertiesにはいくつかの制限があります。これらの制限を文書化しました here 。

Chen Levy · Answer

まず、 additionalPropertiesのより良い説明を見つけました。

オブジェクトの場合、これを指定すると、propertiesで定義されたプロパティに加えて、他のすべてのプロパティ名が許可されます。それらの値はそれぞれ、ここで指定されたスキーマオブジェクトと一致する必要があります。これが指定されていない場合、propertiesで定義されているプロパティ以外のプロパティは許可されません。

だからここに私が最終的にこれを理解した方法があります：

propertiesを使用すると、 Pythonのnamedtuple に似たプロパティの既知のセットを定義できますが、 Pythonのdict またはその他のハッシュのようなものが必要な場合は/ mapでは、キーの数やキーの種類を事前に指定できないため、additionalPropertiesを使用する必要があります。

additionalPropertiesは任意のプロパティ名と一致します（dictのキーとして機能し、$refまたはtypeはdictの値のスキーマになります。特定のオブジェクトごとに同じ名前のプロパティが複数存在しないようにする必要があるため、一意のキーを適用できます。

キーとして不変の値を受け入れるPythonのdictとは異なり、ここでのキーは本質的にプロパティ名であるため、文字列でなければならないことに注意してください。（ありがとう Ted Epstein その説明のため）。この制限は、 json specification のpair := string : valueまで追跡できます。