Open APIs

 View Only

  • 1.  Issue with GeographicLocation @type in openapi specs

    TM Forum Member
    Posted 3 days ago

    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 3 days ago
    Edited by Omar Sood 3 days ago

    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 3 days ago

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

    Original Message