Dlaczego `additionalProperties` jest droga do reprezentowania słownik/MAP w Swagger/OpenAPI 2,0

Question

Chociaż widziałem przykłady w OpenAPI spec:

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

nie jest oczywiste dla mnie dlaczego Używanie additionalProperties jest poprawnym schematem dla mapy/słownika.

To również nie pomaga, że ​​jedyną rzeczą, która beton spec ma do powiedzenia na temat additionalProperties jest:

następujące właściwości zostały zaczerpnięte z definicji JSON Schema ale ich definicje zostały dostosowane do Swagger Specyfikacji . Ich definicja jest taka sama jak w schemacie JSON, tylko tam, gdzie oryginalna definicja odwołuje się do definicji schematu JSON, używana jest definicja obiektu schematu.

• przedmioty
• allOf
• Właściwości
• additionalProperties

Answer 1

Chen, myślę, że your answer jest poprawny.

Niektóre dalsze tło, które mogą być pomocne:

W JavaScript, który był oryginalny kontekst dla JSON, obiekt jest jak mapa hash łańcuchów do wartości, gdzie niektóre wartości są dane, inne funkcje.Każda para nazwa-wartość może być traktowana jako własność. Ale JavaScript nie ma klas, więc nazwy właściwości nie są predefiniowane, a każdy obiekt może mieć własny, niezależny zestaw właściwości.

JSON Schema używa słowa kluczowego properties do sprawdzania par nazwa-wartość, które są znane z góry; i używa additionalProperties (lub patternProperties, nie obsługiwane w OpenAPI 2.0) do sprawdzania właściwości, które nie są znane.

Dla jasności:

• Nazwy własności lub "klucze" w mapie, muszą być łańcuchami. Nie mogą to być liczby ani żadna inna wartość.
• Jak już wspomniano, nazwy nieruchomości powinny być unikatowe w przypadku. Niestety specyfikacja JSON nie wymaga ściśle unikalności, ale unikalność jest zalecana i oczekiwana przez większość implementacji JSON. Więcej tła here.
• properties i additionalProperties mogą być używane samodzielnie lub w połączeniu. Gdy dodatkowe właściwości są używane samodzielnie, bez właściwości, obiekt funkcjonuje zasadniczo jako map<string, T>, gdzie T jest typem opisanym w pod-schemacie AdditionalProperties. Może to pomoże odpowiedzieć na twoje pierwotne pytanie.
• Podczas oceniania obiektu względem pojedynczego schematu, jeśli nazwa właściwości jest zgodna z jedną z tych określonych w properties, jej wartość musi być poprawna tylko względem podukładu podanego dla tej właściwości. Podprogram schematu additionalProperties, jeśli jest dostępny, będzie używany tylko do sprawdzania właściwości, które nie są zawarte na mapie .
• Istnieją pewne ograniczenia związane z additionalProperties, które zostały wprowadzone w podstawowych bibliotekach Java oprogramowania Swagger. Udokumentowałem te ograniczenia here.

Answer 2

Pierwszą rzeczą, znalazłem better explanation for additionalProperties:

dla obiektu, jeśli jest podana, dodatkowo właściwości zdefiniowane w properties wszystkie inne nazwy właściwości są dozwolone. Ich wartości muszą być zgodne z podanym tutaj obiektem schematu. Jeśli nie zostanie podany, nie są dozwolone inne właściwości niż zdefiniowane w properties.

Więc tutaj jest jak w końcu to zrozumiał:

Korzystanie properties możemy zdefiniować znany zestaw właściwości podobnych do Python's namedtuple, jednak jeśli chcemy mieć coś bardziej jak Python's dict lub inny hash/map, gdzie nie możemy określić, ile kluczy istnieje, ani jakie są one z góry, powinniśmy użyć additionalProperties.

additionalProperties będzie pasować do każdego nazwę właściwości (która będzie działać jako dict „klucza s, a $ref lub type będzie schemat na dict” wartość s, a ponieważ nie powinno być więcej niż jeden właściwości o tym samym nazwa dla każdego obiektu, otrzymamy wymuszenie unikalnych kluczy:

Należy zauważyć, że w przeciwieństwie do Pythona dict, który akceptuje dowolną wartość niezmienną jako klucz, ponieważ klucze tutaj są w istocie nazwami właściwości, muszą być ciągami. Ted Epstein dla tego wyjaśnienia). Ograniczenie to można śledzić do pair := string : value w json specification.