ISSUE-234 - Fix API schema inconsistences for r3.2

code/API_definitions/webrtc-call-handling.yaml

@@ -390,9 +390,9 @@
               Update ringing (status update without SDP):
                 $ref: '#/components/examples/exampleStatusChangeRinging'
               Answer with location (callee accepts and shares location):
-                $ref: '#/components/examples/exampleSessionStatusConnectedWithLocation'
+                $ref: '#/components/examples/exampleStatusChangeConnectedWithLocation'
               Location update (post-setup location sharing):
-                $ref: '#/components/examples/exampleSessionStatusLocationUpdate'
+                $ref: '#/components/examples/exampleStatusChangeLocationUpdate'
       responses:
         '200':
           description: |
@@ -448,7 +448,7 @@
       required: true
       style: simple
       explode: false
       schema:
         type: string
         maxLength: 256
     pathParamMediaSessionId:
@@ -458,7 +458,7 @@
       required: true
       style: simple
       explode: false
       schema:
         type: string
         maxLength: 256
     x-correlator:
@@ -475,29 +475,25 @@
       maxLength: 256
       example: "b4333c46-49c0-4f62-80d7-f0ef930f1c46"
     MediaSessionInformation:
-      description: Information about a WebRTC media session including originator and receiver identities, SDP offer/answer, and call status
+      description: Information about a WebRTC media session including originator and receiver identities, SDP offer, call type and location
       type: object
       properties:
         originatorAddress:
           $ref: '#/components/schemas/Address'
         originatorName:
           type: string
           maxLength: 256
           description: Friendly name of the call originator
           example: 'Alice'
         receiverAddress:
           $ref: '#/components/schemas/Address'
         receiverName:
           type: string
           maxLength: 256
           description: Friendly name of the call terminator
           example: 'Bob'
-        status:
-          $ref: '#/components/schemas/SessionStatus'
         offer:
           $ref: '#/components/schemas/WrtcSdpDescriptor'
-        answer:
-          $ref: '#/components/schemas/WrtcSdpDescriptor'
         callType:
           type: string
           description: Type of call. When set to EMERGENCY, the client MAY provide locationDetails. If omitted, treated as REGULAR.
@@ -534,7 +530,11 @@
         - $ref: '#/components/schemas/MediaSessionInformation'
         - type: object
           properties:
+            status:
+              $ref: '#/components/schemas/SessionStatus'
+            answer:
+              $ref: '#/components/schemas/WrtcSdpDescriptor'
             mediaSessionId:
               type: string
               maxLength: 256
               description: >-
@@ -563,18 +563,16 @@
 
         **ANSWER**: This type represents an answer in WebRTC Signaling. This element is not
         present in case there is no answer yet, or the session invitation has
-        been declined by the Terminating Participant.This element MUST NOT be
-        present in a request from the application to the server to create a
-        session.
+        been declined by the Terminating Participant.
       properties:
         sdp:
           type: string
           maxLength: 65536
           description: |-
             An inlined session description in SDP format [RFC4566].If XML syntax is used, the content of this element SHALL be embedded in a CDATA section
     SessionStatus:
       type: string
-      description: Provides the status of the media session. During the session creation, this attribute SHALL NOT be included in the request.
+      description: Provides the status of the media session.
       enum:
         - Initial
         - InProgress
@@ -766,6 +764,40 @@
       description: Example request body used to notify that the receiver endpoint is ringing
       value:
         status: Ringing
+    exampleStatusChangeConnectedWithLocation:
+      summary: Answering party accepts the call and shares their device location
+      description: Example request body used to answer the call with the SDP answer and the answering party's device location
+      value:
+        status: Connected
+        answer:
+          sdp: "v=0\r\no=- 4576312012535546667 4 IN IP4 127.0.0.1\r\ns=-\r\nt=0 0\r\nm=audio 47510 RTP/SAVPF 102 113\r\nc=IN IP6 2001:e0:410:243a:a344:cee7:7b39:bb1e\r\nb=AS:64\r\na=rtcp:9 IN IP4 0.0.0.0\r\na=rtpmap:102 AMR-WB/16000\r\na=fmtp:102 octet-align=0; mode-set=0,1,2; mode-change-capability=2\r\na=rtpmap:113 telephone-event/16000\r\na=ptime:20\r\n"
+        locationDetails:
+          shape: Circle
+          coordinates:
+            latitude: 40.7128
+            longitude: -74.0060
+            radius: 50
+          method: GPS
+          confidence:
+            pdf: normal
+            value: 88
+          timestamp: '2025-10-06T19:32:10Z'
+    exampleStatusChangeLocationUpdate:
+      summary: Post-setup location update by either party
+      description: Example request body used by either call party to share an updated device location after the session is established
+      value:
+        status: Connected
+        locationDetails:
+          shape: Circle
+          coordinates:
+            latitude: 40.7148
+            longitude: -74.0075
+            radius: 30
+          method: GPS
+          confidence:
+            pdf: normal
+            value: 95
+          timestamp: '2025-10-06T19:45:00Z'
     exampleSessionStatus183InProgress:
       description: Session status update indicating the call is in progress (183 Session Progress)
       value:

code/API_definitions/webrtc-events-subscriptions.yaml

@@ -233,11 +233,6 @@
         To subscribe and receive notifications about new calls, a
         `session-invitation` subscription is required using the `deviceId` related to a valid registration.
 
-        For WebRTC calling subscription scenarios, developers should not use
-        `initialEvent` or `subscriptionMaxEvents`. These attributes remain in
-        the schema for CAMARA compatibility, but they are not used by this API
-        for WebRTC calling subscriptions.
-
       operationId: createNotificationChannelSubscription
       parameters:
         - $ref: "#/components/parameters/x-correlator"
@@ -269,7 +264,7 @@
                 consumer. The webrtc-events server will call this endpoint
                 whenever a webrtc-events event occurs. `operationId` value will
                 have to be replaced accordingly with WG API specific semantic.
-              operationId: createNotificationChannelSubscription
+              operationId: postNotification
               parameters:
                 - $ref: "#/components/parameters/x-correlator"
               requestBody:
@@ -406,61 +401,6 @@
           $ref: "../common/CAMARA_common.yaml#/components/responses/PermissionDenied403"
         "404":
           $ref: "../common/CAMARA_common.yaml#/components/responses/NotFound404"
-    put:
-      tags:
-        - Webrtc Events Subscription
-      summary: "Update a webrtc-events event subscription"
-      description: |-
-        Update a given webrtc-events subscription without changing its identity.
-
-        This operation is idempotent. Repeating the same update request results
-        in the same final subscription state.
-
-        Either or both of the following attributes may be updated:
-        - `sinkCredential`
-        - `config.subscriptionExpireTime`
-
-        The subscription `sink`, event types, and `config.subscriptionDetail`
-        are not modified by this operation.
-      operationId: updateNotificationChannelSubscription
-      security:
-        - openId:
-            - webrtc-events-subscriptions:update
-      parameters:
-        - $ref: "#/components/parameters/SubscriptionId"
-        - $ref: "#/components/parameters/x-correlator"
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: "#/components/schemas/SubscriptionUpdateRequest"
-            examples:
-              UPDATE_SUBSCRIPTION:
-                $ref: "#/components/examples/UPDATE_SUBSCRIPTION"
-      responses:
-        "200":
-          description: Updated
-          headers:
-            x-correlator:
-              $ref: "#/components/headers/x-correlator"
-          content:
-            application/json:
-              schema:
-                $ref: "#/components/schemas/Subscription"
-              examples:
-                UPDATED_SUBSCRIPTION:
-                  $ref: "#/components/examples/UPDATED_SUBSCRIPTION"
-        "400":
-          $ref: "#/components/responses/UpdateSubscriptionBadRequest400"
-        "401":
-          $ref: "../common/CAMARA_common.yaml#/components/responses/Unauthenticated401"
-        "403":
-          $ref: "../common/CAMARA_event_common.yaml#/components/responses/SubscriptionPermissionDenied403"
-        "404":
-          $ref: "../common/CAMARA_common.yaml#/components/responses/NotFound404"
-        "429":
-          $ref: "../common/CAMARA_common.yaml#/components/responses/TooManyRequests429"
     delete:
       tags:
         - Webrtc Events Subscription
@@ -570,33 +510,13 @@
         config:
           $ref: "#/components/schemas/Config"
 
-    SubscriptionUpdateRequest:
-      description: |-
-        The request for updating an existing event subscription.
-
-        Either or both of `sinkCredential` and `config.subscriptionExpireTime`
-        may be updated.
-      type: object
-      properties:
-        sinkCredential:
-          $ref: "#/components/schemas/SinkCredential"
-        config:
-          $ref: "#/components/schemas/SubscriptionUpdateConfig"
-      additionalProperties: false
-
     Config:
       description: |-
         Implementation-specific configuration parameters needed by the subscription manager for acquiring
-        events. `subscriptionExpireTime`, `subscriptionMaxEvents`, `initialEvent` are predefined for CAMARA
-        specifications.
+        events. `subscriptionExpireTime` is predefined for CAMARA specifications.
 
         WebRTC specific event type attributes are included into `WebrtcSubscriptionDetail` schema.
 
-        For WebRTC calling subscriptions in this API, developers should use `subscriptionDetail`
-        and, optionally, `subscriptionExpireTime`. The predefined CAMARA attributes
-        `subscriptionMaxEvents` and `initialEvent` are kept for schema alignment and compatibility,
-        but they are not used for WebRTC calling subscription scenarios.
-
         Note: if a request is performed for several event type, all subscribed event will use same `config`
         parameters.
       type: object
@@ -613,38 +533,6 @@
           description: |-
             The subscription expiration time (in date-time format) requested by the API consumer.
             It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone.
-        subscriptionMaxEvents:
-          type: integer
-          format: int32
-          description: Identifies the maximum number of event reports to be generated (>=1) requested by the API consumer - Once this number is reached, the subscription ends. Up to API project decision to keep it.
-          minimum: 1
-          maximum: 1000000
-          example: 5
-        initialEvent:
-          type: boolean
-          description: |-
-            Set to `true` by API consumer if consumer wants to get an event as soon as the subscription is created and current situation reflects event request.
-            Example: Consumer request Roaming event. If consumer sets initialEvent to true and device is in roaming situation, an event is triggered
-            Up to API project decision to keep it.
-
-    SubscriptionUpdateConfig:
-      description: |-
-        Configuration parameters that may be updated for an existing subscription.
-
-        For this API, only `subscriptionExpireTime` may be updated through
-        `PUT /subscriptions/{subscriptionId}`.
-      type: object
-      properties:
-        subscriptionExpireTime:
-          type: string
-          format: date-time
-          maxLength: 64
-          example: "2023-01-17T13:18:23.682Z"
-          description: |-
-            The updated subscription expiration time requested by the API consumer.
-            It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6)
-            and must have time zone.
-      additionalProperties: false
 
     Protocol:
       type: string
@@ -763,7 +651,7 @@
             Camara Event types eligible to be delivered by this subscription.
           type: array
           minItems: 1
-          maxItems: 1
+          maxItems: 3
           items:
             $ref: "#/components/schemas/SubscriptionEventType"
         config:
@@ -815,7 +703,7 @@
       description: The unique identifier of the subscription in the scope of the subscription manager. When this information is contained within an event notification, this concept SHALL be referred as `subscriptionId` as per [Commonalities Event Notification Model](https://github.com/camaraproject/Commonalities/blob/main/documentation/API-design-guidelines.md#122-event-notification).
       example: qs15-h556-rt89-1298
 
     RegistrationId:
       type: string
       maxLength: 256
       description: The unique identifier of the WebRTC registration.
@@ -827,7 +715,7 @@
         - $ref: "../common/CAMARA_event_common.yaml#/components/schemas/CloudEvent"
         - type: object
           properties:
             type:
               type: string
               maxLength: 512
               description: event-type that describes type of notification
@@ -889,17 +777,18 @@
         A prototype for media session infomration on Webrtc events. Used as event data schemas for session updates.
       type: object
       required:
+        - subscriptionId
         - mediaSessionId
       properties:
         subscriptionId:
           $ref: "#/components/schemas/SubscriptionId"
         originatorAddress:
           type: string
           description: Sender (originator) address
-          pattern: '^(tel:\+[0-9]{5,15}|sip:[A-Za-z0-9_.!%+\-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,})$'
+          pattern: '^(tel:\+[1-9][0-9]{4,14}|tel:[0-9*#]{1,15};phone-context=(?:\+[1-9][0-9]{0,14}|[A-Za-z0-9](?:[A-Za-z0-9\-]*[A-Za-z0-9])?(?:\.[A-Za-z0-9](?:[A-Za-z0-9\-]*[A-Za-z0-9])?)+)|sip:[A-Za-z0-9_.!%+\-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}|sip:[0-9*#]{1,15};phone-context=(?:\+[1-9][0-9]{0,14}|[A-Za-z0-9](?:[A-Za-z0-9\-]*[A-Za-z0-9])?(?:\.[A-Za-z0-9](?:[A-Za-z0-9\-]*[A-Za-z0-9])?)+)@[A-Za-z0-9.-]+\.[A-Za-z]{2,};user=phone|urn:service:sos(?:\.[a-z0-9](?:[a-z0-9\-]{0,30}[a-z0-9])?)*|sip:anonymous@anonymous\.invalid)$'
           maxLength: 256
           example: 'tel:+11234567899'
         originatorName:
           type: string
           maxLength: 256
           description: Friendly name of the call originator
@@ -907,10 +796,10 @@
         receiverAddress:
           type: string
           description: Receiver (terminator) address
-          pattern: '^(tel:\+[0-9]{5,15}|sip:[A-Za-z0-9_.!%+\-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,})$'
+          pattern: '^(tel:\+[1-9][0-9]{4,14}|tel:[0-9*#]{1,15};phone-context=(?:\+[1-9][0-9]{0,14}|[A-Za-z0-9](?:[A-Za-z0-9\-]*[A-Za-z0-9])?(?:\.[A-Za-z0-9](?:[A-Za-z0-9\-]*[A-Za-z0-9])?)+)|sip:[A-Za-z0-9_.!%+\-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}|sip:[0-9*#]{1,15};phone-context=(?:\+[1-9][0-9]{0,14}|[A-Za-z0-9](?:[A-Za-z0-9\-]*[A-Za-z0-9])?(?:\.[A-Za-z0-9](?:[A-Za-z0-9\-]*[A-Za-z0-9])?)+)@[A-Za-z0-9.-]+\.[A-Za-z]{2,};user=phone|urn:service:sos(?:\.[a-z0-9](?:[a-z0-9\-]{0,30}[a-z0-9])?)*|sip:anonymous@anonymous\.invalid)$'
           maxLength: 256
           example: 'tel:+11234567899'
         receiverName:
           type: string
           maxLength: 256
           description: Friendly name of the call terminator
@@ -1025,11 +914,9 @@
       description: |-
         - NETWORK_TERMINATED - API server stopped sending notification
         - SUBSCRIPTION_EXPIRED - Subscription expire time (optionally set by the requester) has been reached
-        - MAX_EVENTS_REACHED - Maximum number of events (optionally set by the requester) has been reached
         - ACCESS_TOKEN_EXPIRED - Access Token sinkCredential (optionally set by the requester) expiration time has been reached
         - SUBSCRIPTION_DELETED - Subscription was deleted by the requester
       enum:
-        - MAX_EVENTS_REACHED
         - NETWORK_TERMINATED
         - SUBSCRIPTION_EXPIRED
         - ACCESS_TOKEN_EXPIRED
@@ -1054,9 +941,12 @@
       description: Event detail structure for REGISTRATION_ENDS event. registrationExpireTime is absolute UTC. Clients SHOULD refresh in advance; otherwise a REGISTRATION_EXPIRED terminationReason will be emitted.
       type: object
       required:
+        - subscriptionId
         - registrationId
         - terminationReason
       properties:
+        subscriptionId:
+          $ref: "#/components/schemas/SubscriptionId"
         registrationId:
           $ref: "#/components/schemas/RegistrationId"
         terminationDescription:
@@ -1193,36 +1083,6 @@
           description: Orientation of the ellipsoid in degrees.
 
   responses:
-    UpdateSubscriptionBadRequest400:
-      description: Problem with the client request
-      headers:
-        x-correlator:
-          $ref: "#/components/headers/x-correlator"
-      content:
-        application/json:
-          schema:
-            allOf:
-              - $ref: "../common/CAMARA_common.yaml#/components/schemas/ErrorInfo"
-              - type: object
-                properties:
-                  status:
-                    enum:
-                      - 400
-                  code:
-                    enum:
-                      - INVALID_ARGUMENT
-                      - OUT_OF_RANGE
-                      - INVALID_CREDENTIAL
-                      - INVALID_TOKEN
-          examples:
-            GENERIC_400_INVALID_ARGUMENT:
-              $ref: "../common/CAMARA_common.yaml#/components/examples/GENERIC_400_INVALID_ARGUMENT"
-            GENERIC_400_OUT_OF_RANGE:
-              $ref: "../common/CAMARA_common.yaml#/components/examples/GENERIC_400_OUT_OF_RANGE"
-            GENERIC_400_INVALID_CREDENTIAL:
-              $ref: "../common/CAMARA_event_common.yaml#/components/examples/GENERIC_400_INVALID_CREDENTIAL"
-            GENERIC_400_INVALID_TOKEN:
-              $ref: "../common/CAMARA_event_common.yaml#/components/examples/GENERIC_400_INVALID_TOKEN"
     CreateSubscriptionUnprocessableEntity422:
       description: Unprocessable Content
       headers:
@@ -1334,35 +1194,6 @@
           subscriptionDetail:
             deviceId: "7d444840-9dc0-11d1-b245-5ffdce74fad2"
           subscriptionExpireTime: "2024-11-17T13:18:23.682Z"
-    UPDATE_SUBSCRIPTION:
-      description: |-
-        Example of updating an existing subscription. Either `sinkCredential`,
-        `config.subscriptionExpireTime`, or both may be updated.
-      value:
-        sinkCredential:
-          credentialType: "ACCESSTOKEN"
-          accessToken: "eyJ2ZXIiOiIxLjAiLCJ0eXAiOiJKV1QiL..updated"
-          accessTokenExpiresUtc: "2025-05-01T14:37:56.147Z"
-          accessTokenType: "bearer"
-        config:
-          subscriptionExpireTime: "2025-05-01T13:18:23.682Z"
-    UPDATED_SUBSCRIPTION:
-      description: |-
-        Example of the updated subscription returned after a successful
-        subscription update operation.
-      value:
-        protocol: HTTP
-        sink: https://endpoint.example.com/sink
-        types:
-          - org.camaraproject.webrtc-events-subscriptions.v0.session-status
-        config:
-          subscriptionDetail:
-            deviceId: "3fa85f64-5717-4562-b3fc-2c963f66afa6"
-          subscriptionExpireTime: "2023-01-17T13:18:23.682Z"
-        id: "qs15-h556-rt89-1298"
-        startsAt: "2023-07-03T12:27:08.312Z"
-        expiresAt: "2023-07-03T12:27:08.312Z"
-        status: "ACTIVE"
     # Event examples
     NEW_SESSION_INCOMING:
       description: |-