Open APIs

I am missing the criteria for something: I can see in examples that types are sometimes in lower camel case (voucher) and sometimes in upper camel (Voucher).

I would expect to be Upper case, because they are classes, but for example in swagger for 670 the Payment Method:

"@type": {
                    "type": "string",
                    "enum": [
                        "cash",
                        "digitalWallet",
                        "tokenizedCard",
                        "bankAccountTransfer",
                        "bankAccountDebit",
                        "bankCard",
                        "voucher",
                        "check",
                        "bucketPaymentMethod",
                        "accountPaymentMethod",
                        "loyaltyPaymentMethod",
                        "directDebit"
                    ],
                    "description": "Type of payment method (e.g.: bank card, cash, voucher,etc). "
                }

 But in 676 specifications:

@referredType": "Voucher",

"@type": "bankCard",

From 630 part 1 and 2 mention about the relation between resource and entity but I did not find an explanation there.

When should lower camel case, or the capital be used? 

------------------------------
Jesus Marval
Liberty Latin America
------------------------------

In principle, the Open API conventions dictate that type names (for entities/resources) are camel case starting with upper case (e.g. Voucher, BankCard), while property names are camel case starting with lower case (e.g. id, productSpecification).

It follows that the values for @type, @baseType, @referredType in the examples should all start with upper case.

However, the tooling that we use to validate models and examples does not check this, and so (in v4 APIs) there can be errors both in the generated swagger files and in the examples.

I've scanned the files in v5 for lower-case bankCard, and I found it only in a few examples (which would need to be fixed). The payment method enum for type is implemented differently in v5, since we have oneOf as a schema and swagger capability. 

Hope it helps

"@type": {                    "type": "string",                    "enum": [                        "cash",                        "digitalWallet",                        "tokenizedCard",                        "bankAccountTransfer",                        "bankAccountDebit",                        "bankCard",                        "voucher",                        "check",                        "bucketPaymentMethod",                        "accountPaymentMethod",                        "loyaltyPaymentMethod",                        "directDebit"                    ],                    "description": "Type of payment method (e.g.: bank card, cash, voucher,etc). "                }

@referredType": "Voucher",

"@type": "bankCard",