Circular references in Definitions Object

[vanderlee]

Syntactically, it seems possible to construct an infinite circular reference using Definitions Objects.

Obviously, such a reference could never actually be called or returned. I can't find any conclusive answer on this in the specs. The editor at http://editor.swagger.io/ seems to accept it as valid syntax, but produces an undefined Schema.

How should such a situation be treated?

Example

{
    "swagger": "2.0",
    "info": {
        "title": "vanderlee/PHPSwaggerGen",
        "version": "2.3.7"
    },
    "host": "example.com",
    "basePath": "\/base",
    "paths": {
        "\/customers": {
            "get": {
                "tags": [
                    "Test"
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#\/definitions\/Person"
                        }
                    }
                }
            }
        }
    },
    "definitions": {
        "Address": {
            "type": "object",
            "required": [
                "city",             
        "occupant"
            ],
            "properties": {
                "city": {
                    "type": "string"
                },
                "occupant": {
                    "$ref": "#\/definitions\/Person"
                }
            }
        },
        "Person": {
            "type": "object",
            "required": [
                "name",
                "home"
            ],
            "properties": {
                "name": {
                    "type": "string"
                },
                "home": {
                    "$ref": "#\/definitions\/Address"
                }
            }
        }
    },
    "tags": [
        {
            "name": "Test"
        }
    ]
}

[webron]

Putting tooling aside, what you describe is not something that can actually be represented as a JSON and returned by the API. The circular dependencies is not the issue, it's the fact you made it infinite by requiring the properties to always exist.

Say you want to have an Address that specified the occupant, but also one that can be used to specify the address to a Person, you'd need to break Address to two models, and using them for different purposes.

[vanderlee]

You're pretty much repeating what I said.
Fixing the JSON is not the point.

As far as I can tell, the Open-API spec allows these infinite loops, even though it's impossible in practice (as you reiterated). Shouldn't the spec explicitely forbid such situations or atleast address them in a way that allows implementors to deal with them?

A standard specification document must be unambigious, on this particular issue, it is not.

[webron]

It wasn't clear from your original question what it is that you actually seek.

It's not the job of the spec to deal with such a case. It's JSON Schema that allows it, and not the OpenAPI spec itself. You can do a lot of crazy things or things that won't make sense using JSON Schema, and we allow users to use it for modeling for its common general use, but we cannot safe-guard every case.

[vanderlee]

Okay, too bad the spec will leave in this ambiguity. I'll just add checks to my own tools to prevent users accidentally specifying impossibilities.

[ePaul]

I can imagine people wanting to have such circular dependencies – you'll just have some of the properties being non-required. The actually transmitted object then will have its depth truncated after some level (e.g. by omitting further references from all entities which were already included before).

[SaravanZ]

Hi , Is there any resolution here so far (Open API 2.0, 3.0) ? or this is how the spec is meant to render the references with circular pattern? Thanks.

[tedepstein]

Just read through this, and I think a few points are worth adding, or reiterating:

• Circular references in the schemas do not necessarily imply circular references in the data. It's possible for Person to have properties like spouse, children, or parents that also refer to Person, but will never realistically form a cycle in an actual message.
• Where two or more references form a cycle, making each of those references required does indeed make the schema unsatisfiable. There is no finite message that could possibly conform to the schema. This is just one of many ways to create an unsatisfiable schema. Some of these conditions are potentially easy to detect, but others (like conflicting regular expressions in pattern constraints) are a lot harder to prove satisfiable or not. I suspect this is why JSON Schema (and therefore OpenAPI) decided to leave it up to users.
• What's being called "ambiguity" in the OpenAPI and/or JSON Schema specification is not really ambiguity. It's a partitioning of responsibilities, leaving it up to the user to ensure that schemas are satisfiable and logically consistent. Of course, tools can try to detect and flag logical inconsistencies. The specification doesn't require tools to do this, but it doesn't preclude it.

[SaravanZ]

Thanks for adding your thoughts here.
Re.your first point, not sure what you mean by "realistically form a cycle in an actual message".
To be exact , in my case : The circular reference is more of an object referring to itself. Like an employee - manager relationship.
{
"existingFiles": [
{
"type": "TBC",
"code": "TBC",
"details": "TBC",
"authors": [
{
"type": "TBC",
"fullName": "David Michael Jones",
"title": "TBC",
"firstName": "TBC",
"middleName": "TBC",
"lastName": "TBC",
"coAuthors": [
{
//refer author {}
}
]
}
]
}
]
}

But the Open API spec 2.0 renders null in place of reference in the example and just [] for a model.
To me , what I'm trying to model here is perfectly valid as all author's attributes are applicable to co-authors as well. So I should be able to re-use the definition of author.
I expected the spec would render a model like
"authors":[
{
//attributes
"coAuthors":[{//same attributes as in author}]
}
]
In other words an author object encloses a coAuthors objects array of type author. My team here have created the Java representation of this model without any trouble. So not sure what's contradicting when it comes to the spec or the schemas used within?...

[darrelmiller]

@SaravanZ You keep using phrases like "OpenAPI spec 2.0 renders". The OpenAPI specification doesn't render anything. Do you actually mean the Swagger tooling "renders"?

[SaravanZ]

@darrelmiller for info , I'm not trying to generate any code from the spec etc., all I'm trying to achieve is to describe the model of my API using Open API 2.0 (swagger 2.0). So I think I'm using incorrect terms - so swagger tooling it is (if that is what processes the YAML and renders as specification).

[darrelmiller]

@SaravanZ Swagger-UI is one tool that takes an OpenAPI description and renders HTML documentation of the API. If that's what you are using then I would recommend raising an issue there.

[SaravanZ]

Thanks @darrelmiller. I believe swagger editor that I'm using locally uses the same tooling , so I can raise it there.

[loganfreeman]

It is sad that circular reference could result in Java heap space error.