How to reference to an ID of another model definition in Swagger

Question

Let's assume I have a User and a UserType model. I would like to add a reference to the UserType-ID in the User model. The swagger documentation only shows how to reference to another (whole) model, not just to one of it's properties.

So I was wondering it it's even possible to reference only to a property of another model definition.

"definitions": {
    "User": {
        "required": [
            "username",
            "typeId"
        ],
        "properties": {
            "id": {
                "type": "integer",
                "format": "int32"
            },
            "username": {
                "type": "string"
            },
            "typeId": {
                "$ref": "UserType.id" // ==> this doesn't work! and without
                                      // the ".id" part it would include all
                                      // the properties of UserType
            }
        }
    },
    "UserType": {
        "required": [
            "name"
        ],
        "properties": {
            "id": {
                "type": "integer",
                "format": "int32"
            },
            "name": {
                "type": "string"
            }
        }
    }
}

Or is that not possible at all and it should always be just:

"definitions": {
    "User": {
        ...
        "properties": {
            "typeId": {
                "type": "integer",
                "format": "int32"
            }
        }
    },
    ...
}

Answer 1

In Swagger 2.0, Schema Objects don't necessary describe models (unlike the Model Object in previous versions). For example, if you look at "body" parameters, you'll see you need to define a Schema as the type, but that schema can also represent primitives and arrays.

For the question above (and comments), I'd suggest using the following structure:

"defintions": {
  "User": {
    "required": [
      "username",
      "typeId"
    ],
    "properties": {
      "id": {
        "type": "integer",
        "format": "int32"
      },
      "username": {
        "type": "string"
      },
      "typeId": {
        "$ref": "#/definitions/TypeId"
      }
    }
  },
  "UserType": {
    "required": [
      "name"
    ],
    "properties": {
      "id": {
        "$ref": "#/definitions/TypeId"
      },
      "name": {
        "type": "string"
      }
    }
  },
  "TypeId": {
    "type": "integer",
    "format": "int32"
  }
}

The TypeId is now externalized, and should the time come and you want to change its definition, you can change it in one place. Of course, you may want to add additional "description" to the fields and models to better document the purpose of the.