mapping OpenAPI Dictionaries

January 2025

Dictionaries or maps in OpenAPI are defined with the additionalProperties keyword. To get a java Map<K,V> in the generated code an explicit mapping is necessary.

simple Dictionary

The following OpenAPI schema describes a dictionary of strings or in java terms a Map<String, String>.

components:
  schemas:
    Dictionary:
      type: object
      additionalProperties:
        type: string

The key is always a string and the type: string defines the type of the value. In this case also a string.

Adding mappings for dictionaries works as for any other OpenAPI schema. Mapping the dictionary to Map<String, String> in the generated code use would be:

openapi-processor-mapping: v9

options:
  package-name: io.openapiprocessor.openapi

map:
  types:
    - type: Dictionary => java.util.Map<java.lang.String, java.lang.String>

object Dictionary

The next example uses a schema Foo as value for the string keys:

components:
  schemas:
    FooDictionary:
      type: object
      additionalProperties:
        $ref: '#/components/schemas/Foo'

    Foo:
      type: object
      properties:
        bar: string
        # ...

which would be mapped like this:

openapi-processor-mapping: v9

options:
  package-name: io.openapiprocessor.openapi

map:
  types:
    - type: FooDictionary => java.util.Map<java.lang.String, io.openapiprocessor.openapi.model.Foo>

or a little bit shorter using the {package-name} placeholder.

openapi-processor-mapping: v9

options:
  package-name: io.openapiprocessor.openapi

map:
  types:
    - type: FooDictionary => java.util.Map<java.lang.String, {package-name}.model.Foo>

advanced Dictionary

Dictionaries could also use an array value, for example using array of Foo as value:

components:
  schemas:
    FooDictionary:
      type: object
      additionalProperties:
        type: array
        items:
          $ref: '#/components/schemas/Foo'

    Foo:
      type: object
      properties:
        bar: string
        # ...

The mapping works as expected by nesting generic types:

openapi-processor-mapping: v9

options:
  package-name: io.openapiprocessor.openapi

map:
  types:
    - type: FooDictionary => java.util.Map<java.lang.String, java.util.Collection<{package-name}.model.Foo>>

summary

This short article shows how to create mappings for OpenAPI dictionaries to java Map<K, V>.