Dictionaries, HashMaps and Associative Arrays

A dictionary (also known as a map, hashmap or associative array) is a set of key/value pairs. OpenAPI lets you define dictionaries where the keys are strings. To define a dictionary, use type: object and use the additionalProperties keyword to specify the type of values in key/value pairs. For example, a string-to-string dictionary like this:

1
{ "en": "English", "fr": "French" }

is defined using the following schema:

1
type: object
2
additionalProperties:
3
  type: string

Value Type

The additionalProperties keyword specifies the type of values in the dictionary. Values can be primitives (strings, numbers or boolean values), arrays or objects. For example, a string-to-object dictionary can be defined as follows:

1
type: object
2
additionalProperties:
3
  type: object
4
  properties:
5
    code:
6
      type: integer
7
    text:
8
      type: string

Instead of using an inline schema, additionalProperties can $ref another schema:

1
components:
2
  schemas:
3
    Messages: # <---- dictionary
4
      type: object
5
      additionalProperties:
6
        $ref: "#/components/schemas/Message"
7

8
    Message:
9
      type: object
10
      properties:
11
        code:
12
          type: integer
13
        text:
14
          type: string

Free-Form Objects

If the dictionary values can be of any type (aka free-form object), use additionalProperties: true:

1
type: object
2
additionalProperties: true

This is equivalent to:

1
type: object
2
additionalProperties: {}

Fixed Keys

If a dictionary has some fixed keys, you can define them explicitly as object properties and mark them as required:

1
type: object
2
properties:
3
  default:
4
    type: string
5
required:
6
  - default
7
additionalProperties:
8
  type: string

Examples of Dictionary Contents

You can use the example keyword to specify sample dictionary contents:

1
type: object
2
additionalProperties:
3
  type: string
4
example:
5
  en: Hello!
6
  fr: Bonjour!

Did not find what you were looking for? Ask the community
Found a mistake? Let us know