Swagger model for an array with named elements

Question

Writing the swagger model for a json array seems pretty straightforward to me, e.g. if I had this array:

[
  {
    "name": "dave",
    "number": 123
  },
  {
    "name": "mary",
    "number": 456
  }
]

I would write the following swagger model for it:

"schema": {
  "type": "array",
  "items": {
    "$ref": "Student"
  }
}

"Student": {
  "id": "Student",
  "required": [
    "name",
    "number"
  ],
  "properties": {
    "name": {
      "type": "string"
    },
    "number": {
      "type": "integer",
      "format": "int32"
    }
  }
}

However, I have the following:

{
  "123": {
    "name": "dave"
  },
  "456": {
    "name": "mary"
  }
}

How do I write the model for this one?

Thanks in advance.

Answer 1

To describe the request model, you need to use the additionalProperties properties. Mind you, this is available in Swagger 2.0 and was not available in earlier versions.

"definitions": {
    "Student": {
        "type": "object",
        "required": [ "name" ],
        "properties": {
            "name": {
                "type": "string"
            }
        }
    },
    "Students": {
        "type": "object",
        "additionalProperties": {
            "$ref": "#/definitions/Student"
        }
    }
}

Above you see the Student model, which currently contains the "name" property, though I assume you'll add more to it. From your example above, the "name" property is required.

The second model is Students which is an object that contains a map (additionalProperties). Each property is of the Student type (done by referencing the model, but theoretically could have been defined inline).

The one thing you cannot do is declare that the key (or property name) is an integer or of a given type. That could have been supported with the patternedProperties which is not available in Swagger 2.0. In other words, there's no technical way of limiting the content of the key.