Permit a new top-level entry 'pathDefinitions', capable of containing…

[MattSANU]

… a list of Path Items.

At the moment, one can refer to an external path definition using a reference object, eg:

"paths": {
    "/icecream": {
        "$ref": "example.com/#/pathDefinitions/icecream"
    }
}

However, the reference must be to a definition located in an external document. It cannot refer to the referring document (using '#/' syntax), because there is nowehere in the Swagger API spec other than the 'paths' item where it is legal to place a Path Item object.

In other words, this change permits the previously-illegal:

"pathDefinitions": {
    "IceCreamPath": {
        "get": {
            "summary": "Obtain ice cream"
        }
    }
}
"paths": {
    "/icecream": {
        "$ref": "#/pathDefinitions/IceCreamPath"
    }
}

This is consistent with other aspects of Swagger including parameters, definitions and schemas.

Once we can refer to existing path definitions by name like this, we can add high-level semantic information to the API specification by cross-linking related paths and/or operations - perhaps something like:

"pathDefinitions": {
    "IceCreamPath": {
        "get": {
            "summary": "Obtain ice cream"
        },
        "links": [
            {
                "rel": "self",
                "href": {
                    "$ref": "#/pathDefinitions/IceCreamPath"
                }
            },
            {
                "rel": "topping",
                "href": {
                    "$ref": "#/pathDefinitions/ToppingPath"
                }
            }
        ]
    },
    "ToppingPath": {
        "get": {
            "summary": "Obtain chocolate topping"
        }
    }
},
"paths": {
    "/icecream": {
        "$ref": "#/pathDefinitions/IceCreamPath"
    },
    "/topping": {
        "$ref": "#/pathDefinitions/ToppingPath"
    }

[webron]

@MattSANU - thank you, but this is not how we operate. Spec changes are done once in a while in an organized process, and not just by submitting PRs to change the structure of the current spec. If you feel something needs to be changed, you're more than welcome to open an issue, describe your use case, what you're trying to solve and the necessity of it. If the feature is important enough, and gains enough traction from other users, it may get in a future version of the spec.

[MattSANU]

Understood. I believe issue #239 already contains everything necessary - I share the same use case as the creator of that issue, which I said in that issue. Basically, we both want to implement HATEOAS.

[webron]

@MattSANU - thanks for understanding. Your input is valuable, and it definitely helps us shape the future of the spec. Feel free to add more comments, open new feature requests and so on.