Question, Specification Ambiguity: Using of "allOf: []"

[ivanignatiev]

Which of model difinitions respects the specification 2.0 ?

First:

"ApplicationGatewayIPConfiguration": {
    "properties": {
        "properties": {
            "x-ms-client-flatten": true,
            "$ref": "#/definitions/ApplicationGatewayIPConfigurationPropertiesFormat"
        },
        "name": {
            "type": "string",
            "description": "Gets name of the resource that is unique within a resource group. This name can be used to access the resource"
        },
        "etag": {
            "type": "string",
            "description": "A unique read-only string that changes whenever the resource is updated"
        }
    },
    "allOf": [{
        "$ref": "#/definitions/SubResource"
    }],
    "description": "IP configuration of application gateway"
}

or second? :

"ApplicationGatewayIPConfiguration": {
    "allOf": [{
        "$ref": "#/definitions/SubResource"
    },
    {
        "type": "object",
                "properties": {
            "properties": {
                "x-ms-client-flatten": true,
                "$ref": "#/definitions/ApplicationGatewayIPConfigurationPropertiesFormat"
            },
            "name": {
                "type": "string",
                "description": "Gets name of the resource that is unique within a resource group. This name can be used to access the resource"
            },
            "etag": {
                "type": "string",
                "description": "A unique read-only string that changes whenever the resource is updated"
            }
        }
    }],
    "description": "IP configuration of application gateway"
}

The question is appeared because Swagger CodeGen ignore the first definition, but Azure Rest API uses it ( https://github.com/Azure/azure-rest-api-specs/blob/master/arm-network/2016-03-30/swagger/network.json ). In the specification we can find examples and descriptions related only to the second case.

[ePaul]

All the examples in the 2.0 spec follow the second version, i.e. there are no schema siblings of allOf (just maybe a description or similar). I would guess this is what the authors of the spec intended.

Though from reading the 2.0 spec as well as the referenced JSON Schema spec, I can not find anything which would forbid the first version, though. We should make that clearer in the next version of the Spec.

[IvanGoncharov]

JSON Schema requires the first form in order to support anyOf, oneOf and not in addition to allOf.
Plus it solves priority order for keywords like default, it's clear which one to use in case of inheritance.
And I think it's a bad idea to increase the number of discrepancies between JSON Schema and Swagger, see #333.
Finally, it's hard to be sure which keywords except description to allow on the top level, for e.g. example keyword should be also allowed.

[webron]

They are both technically supported by the spec. The reason the first variant doesn't exist in any of the examples is due to lack of awareness at the time of writing and not as an intentional restriction. I believe the codegen couldn't support it because the parser didn't support it, but that's not the case anymore. This should be handled by the codegen project.