search

camaraproject / DeviceLocation

Repository to describe, develop, document and test the DeviceLocation API family
Apache License 2.0
21 stars 33 forks source link

Use object name in discriminator mapping #121

Closed patrice-conil closed 9 months ago

patrice-conil commented 9 months ago

Problem description In Area, the mapping uses CIRCLE to reference the Circle object... but CIRCLE should be Circle

Expected behavior The left side of the mapping should be the object name, as explained in the design guidelines, to simplify implementation and consumption.

Alternative solution

        mapping:
          Circle: "#/components/schemas/Circle"

    AreaType:
      type: string
      description: |
        Type of this area.
        Circle - The area is defined as a circle.
      enum:
        - Circle
jlurien commented 9 months ago

Hi @patrice-conil,

We recently had the same discussion around mapping for eventType discriminator in CloudEvents. mapping in OAS 3 was introduced precisely to allow having independence between enum values and schema names. If both are the same, the mapping is redundant, OAS3 does not mandate to use it.

The key for mapping is the enum value, and we historically use UPPER_SNAKE_CASE for them, or kebab-case in the case of CloudEvents, while for schema names we use UpperCamelCase. So there is an inconsistency in the guidelines if we ask on one hand to be the same value, and on the other, to have same different formats.

Here we could adopt UpperCamelCase for "Circle" and it would work, But in geofencing we hace CloudEvents and we have the same situation.

patrice-conil commented 9 months ago

Hi @patrice-conil,

We recently had the same discussion around mapping for eventType discriminator in CloudEvents. mapping in OAS 3 was introduced precisely to allow having independence between enum values and schema names. If both are the same, the mapping is redundant, OAS3 does not mandate to use it.

The key for mapping is the enum value, and we historically use UPPER_SNAKE_CASE for them, or kebab-case in the case of CloudEvents, while for schema names we use UpperCamelCase. So there is an inconsistency in the guidelines if we ask on one hand to be the same value, and on the other, to have same different formats.

Here we could adopt UpperCamelCase for "Circle" and it would work, But in geofencing we hace CloudEvents and we have the same situation.

@jlurien, you're right, I close this one.