Open APIs

 View Only
  • 1.  @type @baseType @referredType Naming Convetion

    TM Forum Member
    Posted May 09, 2024 15:49
    Edited by Jesus Marval May 09, 2024 22:20

    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": [
                        "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

  • 2.  RE: @type @baseType @referredType Naming Convetion

    TM Forum Member
    Posted May 12, 2024 05:48

    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

    Jonathan Goldberg
    Amdocs Management Limited
    Any opinions and statements made by me on this forum are purely personal, and do not necessarily reflect the position of the TM Forum or my employer.