CloudEvent schema object in DeviceStatus OpenAPI does not match with CloudEvent schema specified in Commonalities

[mikhilsanghvi]

Problem description data is a required param in CloudEvent schema as per CAMARA commonality specified in https://github.com/camaraproject/Commonalities/blob/main/artifacts/notification-as-cloud-event.yaml

But in the DeviceStatus OpenAPI spec data is defined as a mandatory param and hence conflicting.

Expected behavior data should be optional in CloudEvent schema object in DeviceStatus OpenAPI

Alternative solution An alternative could be that data is made required in all Event* schema objects (EventSubscriptionEnds, EventConnectivityDisconnected, EventConnectivitySms, etc..)

[maxl2287]

Hi @mikhilsanghvi,

Thank you for reporting your issue.

According to the API Design Guidelines, the data parameter is marked as optional (**) with a footnote:

(**) Event data (domain-specific information about the occurrence) are encapsulated within the data object. Its occurrence can be set to mandatory by a given CAMARA API, and its structure is dependent on each API.

For the DeviceStatus API, we decided to mark the data parameter as mandatory for all events. This aligns with your Alternative Solution.

Based on the current main branch and the previous release, this solution is already in place.

Example

    CloudEvent:
      description: The notification callback
      required:
        - id
        - source
        - specversion
        - type
        - time
        - data
      properties:
        #...
        type:
          $ref: "#/components/schemas/NotificationEventType"
        #...
        data:
          type: object
          description: Event details payload described in each CAMARA API and referenced by its type
        #...
      discriminator:
        propertyName: "type"
        mapping:
          org.camaraproject.device-status.v0.roaming-status: "#/components/schemas/EventRoamingStatus"
          # ...

    EventRoamingStatus:
      description: event structure for roaming status change
      allOf:
        - $ref: "#/components/schemas/CloudEvent"
        - type: object
          properties:
            data:
              $ref: "#/components/schemas/RoamingStatus"

[maxl2287]

@mikhilsanghvi does this fit for you? If yes, then we could close this issue.

[maxl2287]

Closed as no response from @mikhilsanghvi was provided.