dictionary - ¿Por qué ''propiedad adicional'' es la forma de representar Diccionario/Mapa en Swagger/OpenAPI 2.0?

hash mapping

Question

Aunque he visto los ejemplos en la especificación OpenAPI :

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

No es obvio para mí por qué el uso de additionalProperties es el esquema correcto para un mapa / diccionario.

Tampoco ayuda que lo único concreto que la especificación tiene que decir sobre additionalProperties es:

Las siguientes propiedades se toman de la definición del esquema JSON, pero sus definiciones se ajustaron a la especificación Swagger. Su definición es la misma que la del esquema JSON, solo cuando la definición original hace referencia a la definición del esquema JSON, en su lugar se utiliza la definición del objeto del esquema.

• artículos
• todo
• propiedades
• Propiedades adicionales

Answer 1

Chen, creo que tu respuesta es correcta.

Algunos antecedentes adicionales que pueden ser útiles:

En JavaScript, que era el contexto original de JSON, un objeto es como un mapa hash de cadenas a valores, donde algunos valores son datos, otros son funciones. Puede pensar en cada par nombre-valor como una propiedad. Pero JavaScript no tiene clases, por lo que los nombres de las propiedades no están predefinidos y cada objeto puede tener su propio conjunto independiente de propiedades.

El esquema JSON utiliza la palabra clave de properties para validar pares nombre-valor que se conocen de antemano; y utiliza patternProperties additionalProperties (o patternProperties , no compatibles con OpenAPI 2.0) para validar propiedades que no se conocen.

Para mayor claridad:

• Los nombres de propiedad, o "claves" en el mapa, deben ser cadenas. No pueden ser números ni ningún otro valor.
• Como dijiste, los nombres de las propiedades deben ser únicos. Desafortunadamente, la especificación JSON no requiere estrictamente unicidad, pero la unicidad es recomendada y esperada por la mayoría de las implementaciones de JSON. Más antecedentes here .
• properties y properties additionalProperties se pueden usar solas o en combinación. Cuando adicionalProperties se usa solo, sin propiedades, el objeto funciona esencialmente como un map<string, T> donde T es el tipo descrito en el sub-esquema de propiedad adicional. Tal vez eso ayude a responder tu pregunta original.
• Al evaluar un objeto contra un esquema único, si el nombre de una propiedad coincide con uno de los especificados en las properties , su valor solo debe ser válido contra el subesquema proporcionado para esa propiedad. El sub-esquema de propiedades additionalProperties , si se proporciona, solo se usará para validar propiedades que no están incluidas en el mapa de properties .
• Existen algunas limitaciones de propiedades additionalProperties implementadas en las bibliotecas principales de Java de Swagger. He documentado estas limitaciones here .

Answer 2

Lo primero, encontré una mejor explicación para propiedades additionalProperties :

Para un objeto, si se proporciona, además de las propiedades definidas en las propiedades, se permiten todos los demás nombres de propiedades. Cada uno de sus valores debe coincidir con el objeto de esquema que se proporciona aquí. Si esto no se da, no se permiten otras propiedades que las definidas en las properties .

Así que así es como finalmente entendí esto:

Usando properties , podemos definir un conjunto conocido de propiedades similares a la tupla nombrada de Python , sin embargo, si deseamos tener algo más como el dict de Python , o cualquier otro hash / mapa donde no podamos especificar cuántas claves hay ni en qué están. de antemano, debemos usar additionalProperties .

additionalProperties coincidirá con cualquier nombre de propiedad (que actuará como la clave del dict , y $ref o type será el esquema del valor del dict , y dado que no debe haber más de una propiedad con el mismo nombre para cada dado el objeto, obtendremos la aplicación de claves únicas.

Tenga en cuenta que, a diferencia del dict de Python que acepta cualquier valor inmutable como clave, dado que las claves aquí son en esencia nombres de propiedad, deben ser cadenas. (Gracias Ted Epstein por esa aclaración). Esta limitación se puede rastrear para pair := string : value en la especificación json .