Open APIs

 View Only
  • 1.  Issue with GeographicLocation @type in openapi specs

    TM Forum Member
    Posted Jun 25, 2024 07:34

    Hello,
    I'm looking for advise how others handle polymorphism with @type in openapi generated code in combination with enum types. Especially in in the context of TMF622 product ordering and GeographicLocation

    TMF622 v5

        GeographicLocation_MVO:
          allOf:
            - $ref: '#/components/schemas/Place_MVO'
            - type: object
              description: >-
                A GeographicLocation is a pure-virtual super-class to the GeoJSON-aligned geometries of
                Point (addresses and locations), MultiPoint, LineString (streets, highways and
                boundaries), MultiLineString and Polygon (countries, provinces, tracts of land). Use the
                @type attribute to specify which of these is being specified by the geometry attribute.
              properties:
                id:
                  type: string
                  description: Unique identifier of the geographic location
                href:
                  type: string
                  description: An URI used to access to the geographic location resource
                '@type':
                  type: string
                  enum:
                    - GeoJsonPoint
                    - GeoJsonMultiPoint
                    - GeoJsonLineString
                    - GeoJsonMultiLineString
                    - GeoJsonPolygon
                  description: The name of the GeoJSON structure used in the geometry attribute
                bbox:
                  type: array
                  description: >-
                    A bounding box array that contains the geometry. The axes order follows the axes
                    order of the geometry
                  items:
                    type: number

    First of all, there seems to be an error in the Spec, because we also got

        GeographicLocationRefOrValue:
          type: object
          description: >-
            The polymorphic attributes @type, @schemaLocation & @referredType are related to the
            GeographicLocation entity and not the GeographicLocationRefOrValue class itself
          oneOf:
            - $ref: '#/components/schemas/GeographicLocation'
            - $ref: '#/components/schemas/GeographicLocationRef'
          discriminator:
            propertyName: '@type'
            mapping:
              GeographicLocation: '#/components/schemas/GeographicLocation'
              GeographicLocationRef: '#/components/schemas/GeographicLocationRef'

    Now, in case of GeographicLocation, @type has to be 'GeographicLocation' and e.g. 'GeoJsonPoint' at the same time. This doesn't work. Shouldn't the discriminator be baseType in this case and GeographicLocation::@baseType equal 'GeographicLocation' at all times?

    There is a second, more implementation specific issue. GeographicLocation inherits

        Extensible:
          type: object
          description: >-
            Base Extensible schema for use in TMForum Open-APIs - When used for in a schema it means
            that the Entity described by the schema  MUST be extended with the @type
          properties:
            '@type':
              type: string
              description: 'When sub-classing, this defines the sub-class Extensible name'
            '@baseType':
              type: string
              description: 'When sub-classing, this defines the super-class'
            '@schemaLocation':
              type: string
              description: A URI to a JSON-Schema file that defines additional attributes and relationships
          required:
            - '@type'

    Java code generation by default will create an Interface Extensible with AtType on the interface due to allOf inheritance This violates type contracts in java, because you can't narrow a string to an enum.

    As a quick workaround we removed the enum values and are looking into a generator customization handle some enums als string and leave it for documentation only. Did anyone else encounter this? Are there some best practices to handle this? I don't like language level enums in generated api code to much anyway, but it's nice to keep the expected values somehow. Advise welcome :)



     



    ------------------------------
    With kind regards
    Omar Sood
    conology
    ------------------------------


  • 2.  RE: Issue with GeographicLocation @type in openapi specs

    TM Forum Member
    Posted Jun 25, 2024 07:43
    Edited by Omar Sood Jun 25, 2024 07:44

    Maybe as a bonus question, what was the reasoning between @type and @baseType with baseType as the super class specifier but mappings usually done on @type level?

    Intuitively, i'd defined a @type for the super class (= concrete without inheritance). In case of multiple levels of inheritance or just more specific business types, i'd have introduced a concrete type like @locationType. This would then allow for even more levels of inheritance, if desired, because you can just define more on demand.

    It seems a bit more complicated to be forced to define either both or select between @baseType or @type depending on how my sub types are defined.



    ------------------------------
    With kind regards
    Omar Sood
    conology



  • 3.  RE: Issue with GeographicLocation @type in openapi specs

    TM Forum Member
    Posted Jun 25, 2024 09:02

    Hi Omar

    I've passed your query on to a focal for the Geo Location API.

    For a general treatment of @type and @baseType please see the design guidelines TMF630



    ------------------------------
    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.
    ------------------------------