Apply Commonaliites 0.8.0 enhancements for device-roaming-status-subscriptions

[bigludo7]

Problem description
Align sim-swap-subscriptions API with commonalities 0.8

List of Commonalities PR relevant for this API

• CAMARA_Common.yaml aligment with multiple device identifiers logic Commonalities#570
• Correcting status code 409 related error information. Commonalities#569
• Fix x-camara-commonalities format Commonalities#537 (automatic fixed by release)
• Clarification meaning of {{API_NAME}}.{{SPECIFIC_CODE}} Commonalities#541
• fix : 'Addr' schema objects updated to 'Address' Commonalities#563
• Array description guideline Commonalities#559
• Guidelines and linting rules for OWASP API Security Top 10 Commonalities#582
• Improve authentication mechanism for subscription events Commonalities#580
• Cloudevents decoupled from EventTypeNotification scheme in Event Subscription Template Commonalities#604
• fix: restructure artifacts directory for $ref consumption Commonalities#606
• Add pagination shared components and example to artifacts Commonalities#617
• Changed response pagination guidelines Commonalities#610
• fix: x-camara-commonalities to use full version string Commonalities#599 (automatic fixed by release)
• Empty Request Body Test proposal. Template Artifact for 400 Syntax Commonalities#618
• fix(design-guide): add rule for undeclared properties in request bodies Commonalities#634
• Add mandatory info.description templates to common artifacts and samples Commonalities#635

List of Commonalities PR not relevant:

• New 409 error code called INCOMPATIBLE_STATE Commonalities#550
• docs: add device identifier constraints per #513 Commonalities#576
• Clarifications for asynchronous responses Commonalities#575
• Add business-level outcome guidance to API Design Guide Commonalities#578
• Refactor Invalid Token Context Error Commonalities#607
• feat: add implicit-subscription API template Commonalities#612
• Cloudevents decoupled from EventTypeNotification scheme in Event Subscription Template Commonalities#604
• fix: inline resource-flavoured 400/422 in implicit-subscription template Commonalities#629

Expected behavior
Fix relevant issue not automatically fixed by release

Alternative solution

Additional context

[rartych]

Here is refactoring plan for device-roaming-status-subscriptions.yaml

Prerequisite: CAMARA_common.yaml and CAMARA_event_common.yaml must be present at code/common/ in the DeviceRoamingStatus repository. All $ref paths below are relative to code/API_definitions/.

---

1. info.description — restructure mandatory blocks

1.1 Remove the ## Further info and support wrapper heading.

1.2 Wrap "Authorization and authentication" with HTML comment markers:

    <!-- CAMARA:MANDATORY:authorization-and-authentication:BEGIN -->
    # Authorization and authentication
    ...
    <!-- CAMARA:MANDATORY:authorization-and-authentication:END -->

1.3 Wrap "Additional CAMARA error responses" with HTML comment markers and fix "may" → "MAY":

    <!-- CAMARA:MANDATORY:additional-error-responses:BEGIN -->
    # Additional CAMARA error responses
    ...
    <!-- CAMARA:MANDATORY:additional-error-responses:END -->

1.4 Add the missing "Request body strictness" mandatory block after additional-error-responses:

    <!-- CAMARA:MANDATORY:request-body-strictness:BEGIN -->
    # Request body strictness

    This API rejects requests with JSON request bodies that contain properties not declared in this specification, at any nesting level. Unknown properties result in a `400 INVALID_ARGUMENT` response.
    <!-- CAMARA:MANDATORY:request-body-strictness:END -->

1.5 Wrap "Identifying the device from the access token" with HTML comment markers; fix ### Error handling: → ## Error handling:; remove the standalone ## Identifying the device from the access token heading (it is included inside the BEGIN marker text):

    <!-- CAMARA:MANDATORY:identifying-device-from-access-token:BEGIN -->
    # Identifying the device from the access token
    ...
    <!-- CAMARA:MANDATORY:identifying-device-from-access-token:END -->

---

2. info.x-camara-commonalities

# Before:
  x-camara-commonalities: 0.6
# After:
  x-camara-commonalities: 0.8

---

3. components/securitySchemes

# Before (inline):
    openId:
      type: openIdConnect
      openIdConnectUrl: https://example.com/.well-known/openid-configuration
    notificationsBearerAuth:
      type: http
      scheme: bearer
      bearerFormat: "{$request.body#/sinkCredential.credentialType}"

# After ($ref):
    openId:
      $ref: "../common/CAMARA_common.yaml#/components/securitySchemes/openId"
    notificationsBearerAuth:
      $ref: "../common/CAMARA_event_common.yaml#/components/securitySchemes/notificationsBearerAuth"

---

4. components/parameters and components/headers

4.1 Remove inline x-correlator parameter definition. Update all 6 operation-level refs to:

$ref: "../common/CAMARA_common.yaml#/components/parameters/x-correlator"

4.2 Remove inline x-correlator header definition. Update all refs in response headers and callback response headers to:

$ref: "../common/CAMARA_common.yaml#/components/headers/x-correlator"

4.3 Update SubscriptionId parameter schema ref:

# Before:
      schema:
        $ref: "#/components/schemas/SubscriptionId"
# After:
      schema:
        $ref: "../common/CAMARA_event_common.yaml#/components/schemas/SubscriptionId"

---

5. paths GET /subscriptions — add pagination

5.1 Add two query parameters after x-correlator:

        - $ref: "../common/CAMARA_common.yaml#/components/parameters/page"
        - $ref: "../common/CAMARA_common.yaml#/components/parameters/perPage"

5.2 Add pagination response headers to 200 response:

          headers:
            x-correlator:
              $ref: "../common/CAMARA_common.yaml#/components/headers/x-correlator"
            X-Total-Count:
              $ref: "../common/CAMARA_common.yaml#/components/headers/x-total-count"
            X-Total-Pages:
              $ref: "../common/CAMARA_common.yaml#/components/headers/x-total-pages"
            Link:
              $ref: "../common/CAMARA_common.yaml#/components/headers/link"

5.3 Replace inline array schema with SubscriptionList (keep existing examples):

# Before:
              schema:
                type: array
                minItems: 0
                items:
                  $ref: '#/components/schemas/Subscription'
              examples:
                List of Subscriptions:
                  $ref: "#/components/examples/SUBSCRIPTION_LIST"
                Empty List of Subscriptions:
                  $ref: "#/components/examples/EMPTY_SUBSCRIPTION_LIST"
# After:
              schema:
                $ref: "#/components/schemas/SubscriptionList"
              examples:
                List of Subscriptions:
                  $ref: "#/components/examples/SUBSCRIPTION_LIST"
                Empty List of Subscriptions:
                  $ref: "#/components/examples/EMPTY_SUBSCRIPTION_LIST"

---

6. paths POST /subscriptions

6.1 Callback request body schema — CloudEvent → NotificationEvent (all examples kept):

# Before:
                      $ref: "#/components/schemas/CloudEvent"
# After:
                      $ref: "#/components/schemas/NotificationEvent"

---

7. components/schemas

7a. SubscriptionRequest — align to template

# sink — add maxLength:
          maxLength: 2048

# protocol ref:
          $ref: "../common/CAMARA_event_common.yaml#/components/schemas/Protocol"

# sinkCredential ref:
          $ref: "../common/CAMARA_event_common.yaml#/components/schemas/SinkCredential"

# types description — replace:
            Note: for the current Commonalities version (v0.5) only one event type per subscription is allowed, yet in the following releases use of array of event types SHALL be specified without changing this definition.
# with:
            References DeviceRoamingEventType (not the full NotificationEvent union) —
            subscription requests target API-specific events only; lifecycle
            events are server-initiated and cannot be subscribed to directly.
            Note: only one event type per subscription is supported.

# types items — rename SubscriptionEventType → DeviceRoamingEventType:
            $ref: "#/components/schemas/DeviceRoamingEventType"

# config ref — stays local (API-specific CreateSubscriptionDetail):
          $ref: "#/components/schemas/Config"

# discriminator mapping — comment out future protocols:
        mapping:
          HTTP: "#/components/schemas/HTTPSubscriptionRequest"
          # Future protocol support (not yet used in CAMARA):
          # MQTT3: "#/components/schemas/MQTTSubscriptionRequest"
          # MQTT5: "#/components/schemas/MQTTSubscriptionRequest"
          # AMQP: "#/components/schemas/AMQPSubscriptionRequest"
          # NATS: "#/components/schemas/NATSSubscriptionRequest"
          # KAFKA: "#/components/schemas/ApacheKafkaSubscriptionRequest"

7b. Remove Protocol — delegate to common

Remove inline definition. The $ref in SubscriptionRequest and Subscription becomes:

$ref: "../common/CAMARA_event_common.yaml#/components/schemas/Protocol"

7c. Config — align to template (stays local)

The local Config stays local because subscriptionDetail references the API-specific CreateSubscriptionDetail (which adds the device property). Align only structural/constraint fields; do not apply template guidance text ("Up to API project decision to keep it."):

Field	Change
description trailing . after subscriptionDetail	Add
description Note wording	event type → event types, subscribed event → subscribed events
subscriptionExpireTime	Add maxLength: 64 only; keep existing description text
subscriptionMaxEvents	Add format: int32; add maximum: 1000000; keep existing description text
initialEvent	Keep description text as-is

7d. Remove SinkCredential, PlainCredential, AccessTokenCredential, RefreshTokenCredential

SinkCredential        → $ref: "../common/CAMARA_event_common.yaml#/components/schemas/SinkCredential"
PlainCredential       → remove (not used in CAMARA)
AccessTokenCredential → $ref: "../common/CAMARA_event_common.yaml#/components/schemas/AccessTokenCredential"
RefreshTokenCredential → remove (replaced by PrivateKeyJWTCredential in common)

7e. Rename SubscriptionEventType → DeviceRoamingEventType and rewrite description

Rename schema key and all 3 $ref usages. Update description:

    DeviceRoamingEventType:
      type: string
      description: |
        Enum of API-specific event type strings for this API project.
        The reverse-DNS prefix `org.camaraproject.device-roaming-status-subscriptions`
        makes each value globally unique across API groups.
      enum:
        - org.camaraproject.device-roaming-status-subscriptions.v0.roaming-status
        - org.camaraproject.device-roaming-status-subscriptions.v0.roaming-on
        - org.camaraproject.device-roaming-status-subscriptions.v0.roaming-off
        - org.camaraproject.device-roaming-status-subscriptions.v0.roaming-change-country

7f. Subscription — align to template

# sink — add maxLength:
          maxLength: 2048

# Add missing sinkCredential property (after sink):
        sinkCredential:
          $ref: "../common/CAMARA_event_common.yaml#/components/schemas/SinkCredential"

# protocol ref:
          $ref: "../common/CAMARA_event_common.yaml#/components/schemas/Protocol"

# types description — replace:
            Note: for the Commonalities meta-release v0.4 we enforce to have only event type per subscription then for following meta-release use of array MUST be decided
             at API project level.
# with:
            Note: only one event type per subscription is supported.

# types items — rename:
            $ref: "#/components/schemas/DeviceRoamingEventType"

# config ref — stays local:
          $ref: "#/components/schemas/Config"

# id ref:
          $ref: "../common/CAMARA_event_common.yaml#/components/schemas/SubscriptionId"

# startsAt — replace inline type/format/description/example with:
        startsAt:
          $ref: "../common/CAMARA_common.yaml#/components/schemas/DateTime"

# expiresAt — replace inline type/format/description/example with:
        expiresAt:
          $ref: "../common/CAMARA_common.yaml#/components/schemas/DateTime"

# discriminator mapping — comment out future protocols:
        mapping:
          HTTP: "#/components/schemas/HTTPSubscriptionResponse"
          # Future protocol support (not yet used in CAMARA):
          # MQTT3: "#/components/schemas/MQTTSubscriptionResponse"
          # MQTT5: "#/components/schemas/MQTTSubscriptionResponse"
          # AMQP: "#/components/schemas/AMQPSubscriptionResponse"
          # NATS: "#/components/schemas/NATSSubscriptionResponse"
          # KAFKA: "#/components/schemas/ApacheKafkaSubscriptionResponse"

# Remove the inline example: block

7g. Remove Device, DeviceResponse — delegate to common

Device        → $ref: "../common/CAMARA_common.yaml#/components/schemas/Device"
DeviceResponse → $ref: "../common/CAMARA_common.yaml#/components/schemas/DeviceResponse"

7h. Remove device sub-schemas — delegate to common

PhoneNumber             → $ref: "../common/CAMARA_common.yaml#/components/schemas/PhoneNumber"
NetworkAccessIdentifier → $ref: "../common/CAMARA_common.yaml#/components/schemas/NetworkAccessIdentifier"
DeviceIpv4Addr          → remove; all $ref usages → "../common/CAMARA_common.yaml#/components/schemas/DeviceIpv4Address"
SingleIpv4Addr          → remove; all $ref usages → "../common/CAMARA_common.yaml#/components/schemas/SingleIpv4Address"
Port                    → remove; all $ref usages → "../common/CAMARA_common.yaml#/components/schemas/Port"
DeviceIpv6Address       → $ref: "../common/CAMARA_common.yaml#/components/schemas/DeviceIpv6Address"

Note: DeviceIpv4Addr and SingleIpv4Addr are renamed in common (DeviceIpv4Address, SingleIpv4Address). Port.minimum changes from 0 to 1 (absorbed by common).

7i. Update SubscriptionAsync — update id ref

        id:
          $ref: "../common/CAMARA_event_common.yaml#/components/schemas/SubscriptionId"

7j. Remove SubscriptionId, XCorrelator, Source, DateTime — delegate to common

SubscriptionId → $ref: "../common/CAMARA_event_common.yaml#/components/schemas/SubscriptionId"
XCorrelator    → $ref: "../common/CAMARA_common.yaml#/components/schemas/XCorrelator"
Source         → $ref: "../common/CAMARA_event_common.yaml#/components/schemas/Source"
DateTime       → $ref: "../common/CAMARA_common.yaml#/components/schemas/DateTime"

7k. Add SubscriptionList schema (new)

    SubscriptionList:
      description: Response with subscriptions list
      type: object
      required:
        - subscriptions
        - pagination
      properties:
        subscriptions:
          description: Subscriptions list
          type: array
          minItems: 0
          maxItems: 100
          items:
            $ref: "#/components/schemas/Subscription"
        pagination:
          $ref: "../common/CAMARA_common.yaml#/components/schemas/Pagination"

7l. Remove EventTypeNotification

Remove the entire schema. Its role is split between DeviceRoamingEventType and SubscriptionLifecycleEventType.

7m. Remove local CloudEvent — introduce layered architecture (4 new schemas)

    SubscriptionLifecycleEventType:
      type: string
      description: |
        Enum of subscription lifecycle event type strings.
        These are managed by Commonalities and are identical across all CAMARA
        APIs that support explicit subscriptions.
      enum:
        - org.camaraproject.device-roaming-status-subscriptions.v0.subscription-started
        - org.camaraproject.device-roaming-status-subscriptions.v0.subscription-updated
        - org.camaraproject.device-roaming-status-subscriptions.v0.subscription-ended

    SubscriptionLifecycleEvent:
      description: |
        Subscription lifecycle event group, common to all CAMARA APIs that
        support explicit subscriptions.
      allOf:
        - $ref: "../common/CAMARA_event_common.yaml#/components/schemas/CloudEvent"
        - type: object
          properties:
            type:
              $ref: "#/components/schemas/SubscriptionLifecycleEventType"
      discriminator:
        propertyName: type
        mapping:
          org.camaraproject.device-roaming-status-subscriptions.v0.subscription-started: "#/components/schemas/EventSubscriptionStarted"
          org.camaraproject.device-roaming-status-subscriptions.v0.subscription-updated: "#/components/schemas/EventSubscriptionUpdated"
          org.camaraproject.device-roaming-status-subscriptions.v0.subscription-ended: "#/components/schemas/EventSubscriptionEnded"

    ApiNotificationEvent:
      description: |
        API-specific notification event group.
        Extends the CloudEvent envelope and constrains `type` to the set of
        event types defined by this API project.
      allOf:
        - $ref: "../common/CAMARA_event_common.yaml#/components/schemas/CloudEvent"
        - type: object
          properties:
            type:
              $ref: "#/components/schemas/DeviceRoamingEventType"
      discriminator:
        propertyName: "type"
        mapping:
          org.camaraproject.device-roaming-status-subscriptions.v0.roaming-status: "#/components/schemas/EventRoamingStatus"
          org.camaraproject.device-roaming-status-subscriptions.v0.roaming-on: "#/components/schemas/EventRoamingOn"
          org.camaraproject.device-roaming-status-subscriptions.v0.roaming-off: "#/components/schemas/EventRoamingOff"
          org.camaraproject.device-roaming-status-subscriptions.v0.roaming-change-country: "#/components/schemas/EventRoamingChangeCountry"

    NotificationEvent:
      description: |
        Union of all valid notification event groups at the callback endpoint.
      oneOf:
        - $ref: "#/components/schemas/ApiNotificationEvent"
        - $ref: "#/components/schemas/SubscriptionLifecycleEvent"

7n. Update concrete API event schemas — allOf[0]: CloudEvent → ApiNotificationEvent

# EventRoamingStatus, EventRoamingOn, EventRoamingOff, EventRoamingChangeCountry:
      allOf:
        - $ref: "#/components/schemas/ApiNotificationEvent"

7o. Update lifecycle event wrapper schemas — allOf[0]: CloudEvent → SubscriptionLifecycleEvent

# EventSubscriptionStarted, EventSubscriptionUpdated, EventSubscriptionEnded:
      allOf:
        - $ref: "#/components/schemas/SubscriptionLifecycleEvent"

7p. Remove InitiationReason, UpdateReason, TerminationReason — delegate to common

InitiationReason  → $ref: "../common/CAMARA_event_common.yaml#/components/schemas/InitiationReason"
UpdateReason      → $ref: "../common/CAMARA_event_common.yaml#/components/schemas/UpdateReason"
TerminationReason → $ref: "../common/CAMARA_event_common.yaml#/components/schemas/TerminationReason"

Update all $ref usages inside SubscriptionStarted, SubscriptionUpdated, SubscriptionEnded accordingly.

7q. Fix SubscriptionEnded structural bug and align fields

Current definition has three problems:

• Bug 1 — required and properties at top level alongside allOf — invalid in OAS 3.0.
• Bug 2 — Spurious required: [countryCode] inside allOf — countryCode is not a property here.
• Bug 3 — subscriptionId missing from the effective required list.

Rewrite as flat object retaining API-specific device property:

    SubscriptionEnded:
      description: Event detail structure for subscription-ended event
      type: object
      required:
        - terminationReason
        - subscriptionId
      properties:
        device:
          $ref: "#/components/schemas/DeviceResponse"
        subscriptionId:
          $ref: "../common/CAMARA_event_common.yaml#/components/schemas/SubscriptionId"
        terminationReason:
          $ref: "../common/CAMARA_event_common.yaml#/components/schemas/TerminationReason"
        terminationDescription:
          type: string
          maxLength: 512
          description: Description of subscription termination

7r. Protocol-specific schemas

# HTTPSubscriptionRequest — add description; update protocolSettings ref:
    HTTPSubscriptionRequest:
      description: Subscription request for HTTP-based event delivery.
      allOf:
        - $ref: "#/components/schemas/SubscriptionRequest"
        - type: object
          properties:
            protocolSettings:
              $ref: "../common/CAMARA_event_common.yaml#/components/schemas/HTTPSettings"

# HTTPSubscriptionResponse — add description; update protocolSettings ref:
    HTTPSubscriptionResponse:
      description: Subscription resource returned for HTTP-based event delivery.
      allOf:
        - $ref: "#/components/schemas/Subscription"
        - type: object
          properties:
            protocolSettings:
              $ref: "../common/CAMARA_event_common.yaml#/components/schemas/HTTPSettings"

# Remove inline HTTPSettings definition.

# Comment out MQTT/AMQP/Kafka/NATS schemas with $ref to CAMARA_event_common.yaml
# (matching template format).

---

8. components/responses — delegate all to external refs

Remove all 11 inline response definitions and update every $ref in paths:

Local response	External ref
Generic400	$ref: "../common/CAMARA_common.yaml#/components/responses/Generic400"
Generic401	$ref: "../common/CAMARA_common.yaml#/components/responses/Generic401"
Generic403	$ref: "../common/CAMARA_common.yaml#/components/responses/Generic403"
Generic404	$ref: "../common/CAMARA_common.yaml#/components/responses/Generic404"
Generic409	$ref: "../common/CAMARA_common.yaml#/components/responses/Generic409"
Generic410	$ref: "../common/CAMARA_common.yaml#/components/responses/Generic410"
Generic429	$ref: "../common/CAMARA_common.yaml#/components/responses/Generic429"
CreateSubscriptionBadRequest400	$ref: "../common/CAMARA_event_common.yaml#/components/responses/CreateSubscriptionBadRequest400"
SubscriptionIdRequired400	$ref: "../common/CAMARA_event_common.yaml#/components/responses/SubscriptionIdRequired400"
SubscriptionPermissionDenied403	$ref: "../common/CAMARA_event_common.yaml#/components/responses/SubscriptionPermissionDenied403"
CreateSubscriptionUnprocessableEntity422	$ref: "../common/CAMARA_event_common.yaml#/components/responses/CreateSubscriptionUnprocessableEntity422"

---

9. components/examples

9.1 SUBSCRIPTION_LIST — update to SubscriptionList object structure:

    SUBSCRIPTION_LIST:
      description: A list of API consumer subscriptions. If a 3-legged access token is used, the list is specific to the device associated with that token.
      value:
        subscriptions:
          - id: 550e8400-e29b-41d4-a716-446655440000
            ...
        pagination:
          totalCount: 1
          totalPages: 1
          page: 1
          perPage: 20

9.2 EMPTY_SUBSCRIPTION_LIST — update to SubscriptionList object structure:

    EMPTY_SUBSCRIPTION_LIST:
      description: The API consumer either has no subscriptions or, if a 3-legged access token is used, has none for the device associated with that token.
      value:
        subscriptions: []
        pagination:
          totalCount: 0
          totalPages: 0
          page: 1
          perPage: 20

9.3 All other examples — keep as-is.

---

Schemas remaining local after refactoring

Schema	Reason
Config	References local CreateSubscriptionDetail; aligned to template field-by-field
CreateSubscriptionDetail	API-specific: adds device property
SubscriptionRequest	References local DeviceRoamingEventType and Config
Subscription	References local DeviceRoamingEventType and Config
SubscriptionAsync	Thin wrapper
SubscriptionList	New; references local Subscription
DeviceRoamingEventType	API-specific enum
SubscriptionLifecycleEventType	Contains API-name-prefixed strings
SubscriptionLifecycleEvent	Contains API-name-prefixed discriminator mapping
ApiNotificationEvent	Contains API-name-prefixed discriminator mapping
NotificationEvent	Union of the two groups above
EventRoamingStatus/On/Off/ChangeCountry	API-specific concrete events
EventSubscriptionStarted/Updated/Ended	Lifecycle wrappers with API-name prefix
SubscriptionStarted	Retains API-specific device property
SubscriptionUpdated	Retains API-specific device property
SubscriptionEnded	Retains API-specific device property (after bug fix)
BasicDeviceEventData	API-specific event data base
RoamingStatus, RoamingChangeCountry	API-specific event data
CountryCode, CountryName	API-specific
HTTPSubscriptionRequest/Response	Reference local SubscriptionRequest/Subscription

[rartych]

@bigludo7 Proposed updated device-roaming-status-subscriptions.yaml is this fork branch:
https://github.com/rartych/DeviceRoamingStatus/tree/refactor/subscriptions-commonalities-0.8
Validation results can be checked here: https://github.com/rartych/DeviceRoamingStatus/actions/runs/26839819720

[bigludo7]

@rartych @akoshunyadi As discussed I propose to close this one. Indeed it is covered in the PR #78 which it itself from issue #79