Update OAS and test definitions to remove IDENTIFIER_MISMATCH error code

code/API_definitions/device-data-volume-subscriptions.yaml

@@ -180,6 +180,11 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/Subscription"
+              examples:
+                Successful Subscription Creation:
+                  $ref: "#/components/examples/SUBSCRIPTION_CREATION"
+                Successful Subscription Creation With Device Disambiguation:
+                  $ref: "#/components/examples/SUBSCRIPTION_CREATION_WITH_DEVICE_DISAMBIGUATION"
         "202":
           description: Request accepted to be processed. It applies for async creation process.
           headers:
@@ -225,6 +230,11 @@ paths:
                 minItems: 0
                 items:
                   $ref: "#/components/schemas/Subscription"
+              examples:
+                Subscription List:
+                  $ref: "#/components/examples/SUBSCRIPTION_LIST"
+                Empty Subscription List:
+                  $ref: "#/components/examples/EMPTY_SUBSCRIPTION_LIST"
         "400":
           $ref: "#/components/responses/Generic400"
         "401":
@@ -256,8 +266,10 @@ paths:
               schema:
                 $ref: "#/components/schemas/Subscription"
               examples:
-                subscription-active:
-                  $ref: "#/components/examples/SUBSCRIPTION_ACTIVE"
+                Active Subscription:
+                  $ref: "#/components/examples/ACTIVE_SUBSCRIPTION"
+                Active Subscription With Device Disambiguation:
+                  $ref: "#/components/examples/ACTIVE_SUBSCRIPTION_WITH_DEVICE_DISAMBIGUATION"
         "400":
           $ref: "#/components/responses/SubscriptionIdRequired400"
         "401":
@@ -614,6 +626,16 @@ components:
           $ref: "#/components/schemas/DeviceIpv6Address"
       minProperties: 1
 
+    DeviceResponse:
+      description: |
+        An identifier for the end-user equipment able to connect to the network that the response refers to. This parameter is only returned when the API consumer includes the `device` parameter in their request (i.e. they are using a two-legged access token), and is relevant when more than one device identifier is specified, as only one of those device identifiers is allowed in the response.
+
+        If the API consumer provides more than one device identifier in their request, the API provider must return a single identifier which is the one they are using to fulfil the request, even if the identifiers do not match the same device. API provider does not perform any logic to validate/correlate that the indicated device identifiers match the same device. No error should be returned if the identifiers are otherwise valid to prevent API consumers correlating different identifiers with a given end user.
+
+      allOf:
+        - $ref: "#/components/schemas/Device"
+        - maxProperties: 1
+
     PhoneNumber:
       description: A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). In order to be globally unique it has to be formatted in international format, according to E.164 standard, prefixed with '+'.
       type: string
@@ -847,7 +869,7 @@ components:
         - subscriptionId
       properties:
         device:
-          $ref: "#/components/schemas/Device"
+          $ref: "#/components/schemas/DeviceResponse"
         subscriptionId:
           $ref: "#/components/schemas/SubscriptionId"
 
@@ -1334,19 +1356,12 @@ components:
                       - 422
                   code:
                     enum:
-                      - IDENTIFIER_MISMATCH
                       - MISSING_IDENTIFIER
                       - MULTIEVENT_SUBSCRIPTION_NOT_SUPPORTED
                       - SERVICE_NOT_APPLICABLE
                       - UNNECESSARY_IDENTIFIER
                       - UNSUPPORTED_IDENTIFIER
           examples:
-            GENERIC_422_IDENTIFIER_MISMATCH:
-              description: Inconsistency between identifiers not pointing to the same device
-              value:
-                status: 422
-                code: IDENTIFIER_MISMATCH
-                message: Provided identifiers are not consistent.
             GENERIC_422_SERVICE_NOT_APPLICABLE:
               description: Service not applicable for the provided identifier
               value:
@@ -1478,7 +1493,65 @@ components:
           subscriptionId: dv10-h556-rt89-1403
         time: "2024-03-05T15:00:23.682Z"
 
-    SUBSCRIPTION_ACTIVE:
+    SUBSCRIPTION_CREATION:
+      description: A new subscription has been successfully created
+      value:
+        protocol: HTTP
+        protocolSettings:
+          method: POST
+        sink: https://endpoint.example.com/sink
+        types:
+          - org.camaraproject.device-data-volume-subscriptions.v0.data-50-percent
+        config:
+          subscriptionDetail: {}
+          subscriptionExpireTime: '2023-01-17T13:18:23.682Z'
+          subscriptionMaxEvents: 5
+          initialEvent: true
+        id: 550e8400-e29b-41d4-a716-446655440000
+        status: ACTIVE
+        startsAt: '2023-01-17T12:27:08.312Z'
+        expiresAt: '2023-01-17T13:18:23.682Z'
+
+    SUBSCRIPTION_CREATION_WITH_DEVICE_DISAMBIGUATION:
+      description: A new subscription has been successfully created
+      value:
+        protocol: HTTP
+        protocolSettings:
+          method: POST
+        sink: https://endpoint.example.com/sink
+        types:
+          - org.camaraproject.device-data-volume-subscriptions.v0.data-50-percent
+        config:
+          subscriptionDetail:
+            device:
+              phoneNumber: "+123456789"
+          subscriptionExpireTime: '2023-01-17T13:18:23.682Z'
+          subscriptionMaxEvents: 5
+          initialEvent: true
+        id: 550e8400-e29b-41d4-a716-446655440000
+        status: ACTIVE
+        startsAt: '2023-01-17T12:27:08.312Z'
+        expiresAt: '2023-01-17T13:18:23.682Z'
+
+    ACTIVE_SUBSCRIPTION:
+      description: Details of an active subscription
+      value:
+        id: 550e8400-e29b-41d4-a716-446655440001
+        sink: https://endpoint.example.com/sink
+        protocol: HTTP
+        types:
+          - "org.camaraproject.device-data-volume-subscriptions.v0.data-exceeded"
+        config:
+          subscriptionDetail: {}
+          subscriptionExpireTime: "2024-08-01T14:18:23.682Z"
+          subscriptionMaxEvents: 10
+          initialEvent: true
+        status: ACTIVE
+        startsAt: '2023-01-17T12:27:08.312Z'
+        expiresAt: '2023-01-17T13:18:23.682Z'
+
+    ACTIVE_SUBSCRIPTION_WITH_DEVICE_DISAMBIGUATION:
+      description: Details of an active subscription with device details for disambiguation
       value:
         id: 550e8400-e29b-41d4-a716-446655440001
         sink: https://endpoint.example.com/sink
@@ -1492,5 +1565,27 @@ components:
           subscriptionExpireTime: "2024-08-01T14:18:23.682Z"
           subscriptionMaxEvents: 10
           initialEvent: true
-        startsAt: "2024-06-15T09:30:02.871Z"
-        expiresAt: "2024-08-01T14:18:23.682Z"
+        status: ACTIVE
+        startsAt: '2023-01-17T12:27:08.312Z'
+        expiresAt: '2023-01-17T13:18:23.682Z'
+
+    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:
+        - id: 550e8400-e29b-41d4-a716-446655440001
+          sink: https://endpoint.example.com/sink
+          protocol: HTTP
+          types:
+            - "org.camaraproject.device-data-volume-subscriptions.v0.data-exceeded"
+          config:
+            subscriptionDetail: {}
+            subscriptionExpireTime: "2024-08-01T14:18:23.682Z"
+            subscriptionMaxEvents: 10
+            initialEvent: true
+          status: ACTIVE
+          startsAt: '2023-01-17T12:27:08.312Z'
+          expiresAt: '2023-01-17T13:18:23.682Z'
+
+    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: []

code/API_definitions/device-data-volume.yaml

@@ -12,7 +12,11 @@ info:
 
     # Relevant terms and definitions
 
-    * **Device**: A device refers to any physical entity that can connect to a network and participate in network communication. At least one identifier for the device (user equipment) out of four options: IPv4 address, IPv6 address, Phone number, or Network Access Identifier assigned by the mobile network operator for the device.
+    * **Device**: A device refers to any physical entity that can connect to a network and participate in network communication.
+
+        At least one identifier for the device out of four options must be provided: IPv4 address, IPv6 address, Phone number, or Network Access Identifier assigned by the mobile network operator for the device. Where more than one device identifier is provided, only one identifier will be selected by the implementation and this choice indicated to the API consumer in the session creation response.
+
+        Note: Network Access Identifier is defined for future use and will not be supported with this version of the API.
 
     # API Functionality
 
@@ -101,6 +105,11 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/RetrieveDataVolumeResponse"
+              examples:
+                Successful Response:
+                  $ref: "#/components/examples/SuccessfulRetrieveResponse"
+                Successful Response With Device Disambiguation:
+                  $ref: "#/components/examples/SuccessfulRetrieveResponseWithDeviceDisambiguation"
         "400":
           $ref: "#/components/responses/Generic400"
         "401":
@@ -140,6 +149,11 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/CheckDataVolumeResponse"
+              examples:
+                Successful Response:
+                  $ref: "#/components/examples/SuccessfulCheckResponse"
+                Successful Response With Device Disambiguation:
+                  $ref: "#/components/examples/SuccessfulCheckResponseWithDeviceDisambiguation"
         "400":
           $ref: "#/components/responses/Generic400"
         "401":
@@ -207,6 +221,8 @@ components:
       description: Represents the response, if the data volume exceeds a given threshold.
       type: object
       properties:
+        device:
+          $ref: "#/components/schemas/DeviceResponse"
         thresholdExceeded:
           type: boolean
           description: Indicates whether the remaining data volume exceeds the given threshold
@@ -226,6 +242,8 @@ components:
       description: Represents the remaining data volume of the requested device.
       type: object
       properties:
+        device:
+          $ref: "#/components/schemas/DeviceResponse"
         dataVolumeCategory:
           $ref: "#/components/schemas/DataVolumeCategory"
       required:
@@ -262,6 +280,16 @@ components:
           $ref: "#/components/schemas/DeviceIpv6Address"
       minProperties: 1
 
+    DeviceResponse:
+      description: |
+        An identifier for the end-user equipment able to connect to the network that the response refers to. This parameter is only returned when the API consumer includes the `device` parameter in their request (i.e. they are using a two-legged access token), and is relevant when more than one device identifier is specified, as only one of those device identifiers is allowed in the response.
+
+        If the API consumer provides more than one device identifier in their request, the API provider must return a single identifier which is the one they are using to fulfil the request, even if the identifiers do not match the same device. API provider does not perform any logic to validate/correlate that the indicated device identifiers match the same device. No error should be returned if the identifiers are otherwise valid to prevent API consumers correlating different identifiers with a given end user.
+
+      allOf:
+        - $ref: "#/components/schemas/Device"
+        - maxProperties: 1
+
     PhoneNumber:
       description: A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). In order to be globally unique it has to be formatted in international format, according to E.164 standard, prefixed with '+'.
       type: string
@@ -461,18 +489,11 @@ components:
                       - 422
                   code:
                     enum:
-                      - IDENTIFIER_MISMATCH
                       - MISSING_IDENTIFIER
                       - SERVICE_NOT_APPLICABLE
                       - UNNECESSARY_IDENTIFIER
                       - UNSUPPORTED_IDENTIFIER
           examples:
-            GENERIC_422_IDENTIFIER_MISMATCH:
-              description: Inconsistency between identifiers not pointing to the same device
-              value:
-                status: 422
-                code: IDENTIFIER_MISMATCH
-                message: Provided identifiers are not consistent.
             GENERIC_422_SERVICE_NOT_APPLICABLE:
               description: Service not applicable for the provided identifier
               value:
@@ -499,3 +520,25 @@ components:
                 status: 422
                 code: UNSUPPORTED_IDENTIFIER
                 message: The identifier provided is not supported.
+
+  examples:
+    SuccessfulRetrieveResponse:
+      description: Successfully retrieve the device data volume category
+      value:
+        dataVolumeCategory: "<200MiB"
+    SuccessfulRetrieveResponseWithDeviceDisambiguation:
+      description: Successfully retrieve the device data volume category but device disambiguation is required
+      value:
+        device:
+          phoneNumber: "+123456789"
+        dataVolumeCategory: "<200MiB"
+    SuccessfulCheckResponse:
+      description: Successfully check the device data volume category
+      value:
+        thresholdExceeded: false
+    SuccessfulCheckResponseWithDeviceDisambiguation:
+      description: Successfully check the device data volume category but device disambiguation is required
+      value:
+        device:
+          phoneNumber: "+123456789"
+        thresholdExceeded: true

code/Test_definitions/device-data-volume-checkDataVolume.feature

@@ -132,19 +132,6 @@ Feature: CAMARA Device Data Volume API, vwip - Operation checkDataVolume
     And the response property "$.code" is "SERVICE_NOT_APPLICABLE"
     And the response property "$.message" contains a user-friendly text
 
-  # Several identifiers provided but they do not identify the same device
-  # This scenario may happen with 2-legged access tokens, which do not identify a device
-  @device_data_volume_checkDataVolume_C01.08_device_identifiers_mismatch
-  Scenario: Device identifiers mismatch
-    Given the header "Authorization" is set to a valid access token which does not identify a single device
-    And at least 2 types of device identifiers are supported by the implementation
-    And the request body property "$.device" includes several identifiers, each of them identifying a valid but different device
-    When the request "checkDataVolume" is sent
-    Then the response status code is 422
-    And the response property "$.status" is 422
-    And the response property "$.code" is "IDENTIFIER_MISMATCH"
-    And the response property "$.message" contains a user friendly text
-
 #################
 # Error code 401
 #################

code/Test_definitions/device-data-volume-retrieveDataVolume.feature

@@ -119,19 +119,6 @@ Feature: CAMARA Device Data Volume API, vwip - Operation retrieveDataVolume
     And the response property "$.code" is "SERVICE_NOT_APPLICABLE"
     And the response property "$.message" contains a user-friendly text
 
-  # Several identifiers provided but they do not identify the same device
-  # This scenario may happen with 2-legged access tokens, which do not identify a device
-  @device_data_volume_retrieveDataVolume_C01.08_device_identifiers_mismatch
-  Scenario: Device identifiers mismatch
-    Given the header "Authorization" is set to a valid access token which does not identify a single device
-    And at least 2 types of device identifiers are supported by the implementation
-    And the request body property "$.device" includes several identifiers, each of them identifying a valid but different device
-    When the request "retrieveDataVolume" is sent
-    Then the response status code is 422
-    And the response property "$.status" is 422
-    And the response property "$.code" is "IDENTIFIER_MISMATCH"
-    And the response property "$.message" contains a user friendly text
-
 #################
 # Error code 401
 #################

code/Test_definitions/device-data-volume-subscriptions.feature

@@ -327,19 +327,6 @@ Feature: Device Data Volume Subscriptions API, vwip - Operation createDeviceData
     And the response property "$.code" is "SERVICE_NOT_APPLICABLE"
     And the response property "$.message" contains a user-friendly text
 
- # Several identifiers provided but they do not identify the same device
- # This scenario may happen with 2-legged access tokens, which do not identify a device
-  @device_data_volume_subscriptions_C01.08_device_identifiers_mismatch
-  Scenario: Device identifiers mismatch
-    Given the header "Authorization" is set to a valid access token which does not identify a single device
-    And at least 2 types of device identifiers are supported by the implementation
-    And the request body property "$.device" includes several identifiers, each of them identifying a valid but different device
-    When the request "createDeviceDataVolumeSubscription" is sent
-    Then the response status code is 422
-    And the response property "$.status" is 422
-    And the response property "$.code" is "IDENTIFIER_MISMATCH"
-    And the response property "$.message" contains a user friendly text
-
 ##################
 # Error code 400
 ##################