How to inherit schema properties from another schema?

Question

I'm using ReDoc to visualize API documentation using an OpenAPI 2 (Swagger) JSON file. I'm trying to declare two request input parameters by including the first schema into the second one as follows:

...
"definitions": {
    "list-request": {
        "type": "object",
        "properties": {
            "token":{
                "type": "string",
                "format": "access-token",
                "required": true
            },
            "userId":{
                "type": "integer",
                "required": true,
                "format": "int32"
            },
            "mode": {
                "type": "string",
                "required": false,
                "default": "lite",
                "enum": [
                    "lite",
                    "detailed"
                ]
            },
            ... // other peroperties
        },
        "xml": {
            "name": "list-request"
        }
    },
    "list-request-lite":{
        "$ref": "#/definitions/list-request",
        "properties":{
            "mode": {
                "type": "string",
                "required": false,
                "enum": ["lite"]
            }
        }
    },
    ...
}

But it does not work - the list-request-lite schema just shows the mode property and none of the list-request schema properties are included. What am I doing wrong?

score 2 · Accepted Answer · answered Nov 13 '17 at 08:26

You need allOf to combine a $ref with other properties.

Also, the required properties need to be listed in the required array on the schema level. Individual properties don't have the required attribute.

"definitions": {
  "list-request": {
    "type": "object",
    "properties": {
      "token": {
        "type": "string",
        "format": "access-token"
      },
      "userId": {
        "type": "integer",
        "format": "int32"
      },
      "mode": {
        "type": "string",
        "default": "lite",
        "enum": [
          "lite",
          "detailed"
        ]
      }
    },
    "xml": {
      "name": "list-request"
    },
    "required": [     // <---- required properties for this schema
      "token",
      "userId"
    ]
  },

  "list-request-lite": {
    "allOf": [        // <---------
      {
        "$ref": "#/definitions/list-request"
      },
      {
        "type": "object",
        "properties": {
          "mode": {
            "type": "string",
            "enum": ["lite"]
          }
        }
      }
    ]
  }
}

How to inherit schema properties from another schema?

1 Answers1