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