OAS 3 This page applies to OpenAPI 3 – the latest version of the OpenAPI Specification.

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:
{
  "en": "English",
  "fr": "French"
}
is defined using the following schema:
type: object
additionalProperties:
  type: string

Value Type

The additionalProperty 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:
type: object
additionalProperties:
  type: object
  properties:
    code:
      type: integer
    text:
      type: string
Instead of using an inline schema, additionalProperties can $ref another schema:
components:
  schemas:
    Messages:        # <---- dictionary
      type: object
      additionalProperties:
        $ref: '#/components/schemas/Message'

    Message:
      type: object
      properties:
        code:
          type: integer
        text:
          type: string

Free-Form Objects

If the dictionary values can be of any type (aka free-form object), use additionalProperties: true:
type: object
additionalProperties: true
This is equivalent to:
type: object
additionalProperties: {}

Fixed Keys

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

Examples of Dictionary Contents

You can use the example keyword to specify sample dictionary contents:
type: object
additionalProperties:
  type: string
example:
  en: Hello!
  fr: Bonjour!