Forum Discussion

Rafal's avatar
Rafal
Occasional Visitor
3 years ago

Circular references in OpenAPI

Can someone please inform me if circular references are allowed when using "allOf", "oneOf" and "anyOf" keywords?

The OpenAPI specification does not explicitly say anything about that.

 

Here's an example API specification that causes all sorts of problems when attempting to generate code from it using different code generators.

Essentially I'd like to combine inheritance with polymorphism so that I have an "abstract" type Animal that I can return from any method, and also Animal is never just the base class, it's always either Dog or Cat, both of which inherit some of the Animal's properties.

Is this a valid schema according to OpenAPI 3 specification or not? 

{
    "openapi": "3.0.1",
    "info": {
        "title": "PET API",
        "version": "v1"
    },
    "paths": {
        "/pets/{name}": {
            "get": {
                "responses": {
                    "200": {
                        "description": "Success",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Animal"
                                }
                            }
                        }
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "Animal": {
                "type": "object",
                "oneOf": [{
                        "$ref": "#/components/schemas/Cat"
                    }, {
                        "$ref": "#/components/schemas/Dog"
                    }
                ],
                "properties": {
                    "name": {
                        "type": "string",
                    },
                    "animalType": {
                        "type": "string"
                    }
                },
                "discriminator": {
                    "propertyName": "animalType"
                }
            },
            "Cat": {
                "type": "object",
                "allOf": [{
                        "$ref": "#/components/schemas/Animal"
                    }, {
                        "type": "object",
                        "properties": {
                            "whiskersCount": {
                                "type": "integer",
                            }
                        }
                    }
                ]
            },
            "Dog": {
                "type": "object",
                "allOf": [{
                        "$ref": "#/components/schemas/Animal"
                    }, {
                        "type": "object",
                        "properties": {
                            "tailWagsPerSecond": {
                                "type": "integer",
                            }
                        }
                    }
                ]
            },
        }
    }
}

 

No RepliesBe the first to reply