How to write OpenAPI 3 (Swagger) specification for property name in `map` object?

Question

The API I\'m trying to describe has a structure where the root object can contain an arbitrary number of child objects (properties that are themselves objects). The "ke

Answer 1

Your example is correct.

how do I document what the restrictions are for the "key" in the object? Ideally I'd like to say something like "it's not just any arbitrary string, it's the ID that corresponds to the child". Is this supported in any way?

OpenAPI 3.1 (future version, not yet released)

OAS 3.1 will fully support JSON Schema draft 2019-09, including patternProperties. This keyword lets you to define the format of dictionary keys by using a regular expression:

"Parent": {
  "type": "object",
  "patternProperties": {
    "^child\d+$": {
      "$ref": "#/components/schemas/Child"
    }
  },
  "description": "A map of `Child` schemas, where the keys are IDs that correspond to the child"
}

Or if the property names are defined by an enum, you can use propertyNames to define that enum:

"Parent": {
  "type": "object",
  "propertyNames": {
    "enum": ["foo", "bar"]
  },
  "additionalProperties": {
    "$ref": "#/components/schemas/Child"
  }
}

OpenAPI 3.0 and 2.0

OpenAPI assumes that the keys are strings, but there's currently (as of OpenAPI 3.0) no way to limit the contents/format of keys. You can document any restrictions and specifics verbally in the schema description. Adding schema examples could help illustrate what your dictionary/map might look like.

"Parent": {
  "type": "object",
  "additionalProperties": {
    "$ref": "#/components/schemas/Child"
  },
  "description": "A map of `Child` schemas, where the keys are IDs that correspond to the child",
  "example": {
    "child1": { ... bunch of stuff ... },
    "child2": { ... bunch of stuff ... },
  }

If the possible key names are known (for example, they are part of an enum), you can define your dictionary as a regular object and the keys as individual object properties:

// Keys can be: key1, key2, key3

"Parent": {
   "type": "object",
   "properties": { 
      "key1": { "$ref": "#/components/schemas/Child" },
      "key2": { "$ref": "#/components/schemas/Child" },
      "key3": { "$ref": "#/components/schemas/Child" }
   }
}

Then you can add "additionalProperties": false to really ensure that only those keys are used.