From 6d8ca68b9b334be92ba07280748fd1b47fa3c8dc Mon Sep 17 00:00:00 2001
From: Maximilian Laue <Maximilian.Laue@t-systems.com>
Date: Thu, 6 Jun 2024 23:20:15 +0200
Subject: [PATCH 01/20] feat: update the subscriptions models based on the
 CAMARA commonalities

---
 .../geofencing-subscriptions.yaml             | 1123 ++++++++++++-----
 1 file changed, 796 insertions(+), 327 deletions(-)

diff --git a/code/API_definitions/geofencing-subscriptions.yaml b/code/API_definitions/geofencing-subscriptions.yaml
index e08512e7..2c1b87ae 100644
--- a/code/API_definitions/geofencing-subscriptions.yaml
+++ b/code/API_definitions/geofencing-subscriptions.yaml
@@ -35,6 +35,9 @@ info:
     The CAMARA subscription model is detailed in the CAMARA API design guideline document and follows CloudEvents specification.
 
     It is mandatory in the subscription to provide the event `type` for which the client would like to subscribe.
+    
+    _Note: An array of types could be passed but as of now only one value MUST passed. Use of multiple value will be open later at API level._
+
 
     Following event ``type`` are managed for this API:
       - ``org.camaraproject.geofencing-subscriptions.v0.area-entered``  - Event triggered when the device enters the given area
@@ -51,17 +54,18 @@ info:
 
     ### Notification callback
 
-    This endpoint describes the event notification received on subscription listener side when the event occurred. As for subscription, detailed description of the event notification is provided in the CAMARA API design guideline document.
+    This endpoint describes the event notification received on subscription listener side when the event occurred. 
+    As for subscription, detailed description of the event notification is provided in the CAMARA API design guideline document.
 
-    _**WARNING**: This callback endpoint must be exposed on the consumer side as `POST /{$request.body#/webhook/notificationUrl}`.
+    _**WARNING**: This callback endpoint must be exposed on the consumer side as `POST /{$request.body#/sink}`.
       Developers may provide a callback URL on which notifications regarding geofencing can be received from the service provider.
-      If an event occurs the application will send events to the provided webhook - 'notificationUrl'._
+      If an event occurs the application will send events to the provided webhook - 'sink'._
 
     # Further info and support
 
     (FAQs will be added in a later version of the documentation)
 
-  termsOfService: http://swagger.io/terms/
+  termsOfService: https://swagger.io/terms/
   contact:
     email: project-email@sample.com
   license:
@@ -92,30 +96,35 @@ paths:
       operationId: createSubscription
       parameters:
         - $ref: '#/components/parameters/x-correlator'
+      security:
+        - openId:
+            - geofencing-subscriptions:org.camaraproject.geofencing-subscriptions.v0.area-entered:create
+            - geofencing-subscriptions:org.camaraproject.geofencing-subscriptions.v0.area-left:create
       requestBody:
         content:
           application/json:
             schema:
-              $ref: "#/components/schemas/CreateSubscription"
+              $ref: "#/components/schemas/SubscriptionRequest"
             examples:
               CIRCLE_AREA_ENTERED:
                 $ref: "#/components/examples/REQUEST_CIRCLE_AREA_ENTERED"
         required: true
       callbacks:
-        event-notifications:
-          "{$request.body#/webhook/notificationUrl}":
+        notifications:
+          "{$request.body#/sink}":
             post:
-              summary: "Subscription notification callback"
+              summary: "notifications callback"
               description: |
                 Important: this endpoint is to be implemented by the API consumer.
-                The Device Location server will call this endpoint whenever a device geofencing related event occurs.
+                The Geofencing server will call this endpoint whenever a Geofencing event occurs.
+                `operationId` value will have to be replaced accordingly with WG API specific semantic
               operationId: postNotification
               parameters:
-                - $ref: '#/components/parameters/x-correlator'
+                - $ref: "#/components/parameters/x-correlator"
               requestBody:
                 required: true
                 content:
-                  application/cloudevents+json:
+                  application/json:
                     schema:
                       $ref: "#/components/schemas/CloudEvent"
                     examples:
@@ -130,13 +139,17 @@ paths:
                   description: Successful notification
                   headers:
                     x-correlator:
-                      $ref: '#/components/headers/x-correlator'
+                      $ref: "#/components/headers/x-correlator"
                 "400":
                   $ref: "#/components/responses/Generic400"
                 "401":
                   $ref: "#/components/responses/Generic401"
                 "403":
                   $ref: "#/components/responses/Generic403"
+                "410":
+                  $ref: "#/components/responses/Generic410"
+                "429":
+                  $ref: "#/components/responses/Generic429"
                 "500":
                   $ref: "#/components/responses/Generic500"
                 "503":
@@ -149,48 +162,62 @@ paths:
           description: Created (Successful creation of subscription)
           headers:
             x-correlator:
-              $ref: '#/components/headers/x-correlator'
+              $ref: "#/components/headers/x-correlator"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Subscription"
+        "202":
+          description: Request accepted to be processed. It applies for async creation process.
+          headers:
+            x-correlator:
+              $ref: "#/components/headers/x-correlator"
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/SubscriptionInfo"
+                $ref: "#/components/schemas/SubscriptionAsync"
         "400":
-          $ref: "#/components/responses/Generic400"
+          $ref: "#/components/responses/CreateSubscriptionBadRequest400"
         "401":
           $ref: "#/components/responses/Generic401"
         "403":
-          $ref: "#/components/responses/Generic403"
+          $ref: "#/components/responses/CreateSubscription403"
         "409":
           $ref: "#/components/responses/Generic409"
+        "415":
+          $ref: "#/components/responses/Generic415"
+        "422":
+          $ref: "#/components/responses/CreateSubscription422"
+        "429":
+          $ref: "#/components/responses/Generic429"
         "500":
           $ref: "#/components/responses/Generic500"
         "503":
           $ref: "#/components/responses/Generic503"
-      security:
-        - openId:
-            - geofencing-subscriptions:org.camaraproject.geofencing-subscriptions.v0.area-entered:create
-            - geofencing-subscriptions:org.camaraproject.geofencing-subscriptions.v0.area-left:create
     get:
       tags:
-        - Geofencing subscriptions
-      summary: "Operation to retrieve a list of subscriptions."
-      operationId: getSubscriptionList
-      description: Operation to list subscriptions authorized to be retrieved by the provided access token.
+        - Geofencing Subscription
+      summary: "Retrieve a list of geofencing event subscription"
+      description: Retrieve a list of geofencing event subscription(s)
+      operationId: retrieveGeofencingSubscriptionList
       parameters:
-        - $ref: '#/components/parameters/x-correlator'
+        - $ref: "#/components/parameters/x-correlator"
+      security:
+        - openId:
+            - geofencing-subscriptions:read
       responses:
         "200":
-          description: The list of subscriptions is retrieved.
+          description: List of event subscription details
           headers:
             x-correlator:
-              $ref: '#/components/headers/x-correlator'
+              $ref: "#/components/headers/x-correlator"
           content:
             application/json:
               schema:
                 type: array
                 minItems: 0
                 items:
-                  $ref: "#/components/schemas/SubscriptionInfo"
+                  $ref: '#/components/schemas/Subscription'
         "400":
           $ref: "#/components/responses/Generic400"
         "401":
@@ -201,37 +228,31 @@ paths:
           $ref: "#/components/responses/Generic500"
         "503":
           $ref: "#/components/responses/Generic503"
-      security:
-        - openId:
-            - geofencing-subscriptions:read
-
-  /subscriptions/{subscriptionsId}:
+  /subscriptions/{subscriptionId}:
     get:
       tags:
         - Geofencing subscriptions
       summary: "Operation to retrieve a subscription based on the provided ID"
-      operationId: getSubscription
-      description: Retrieve a given subscription by ID
+      description: retrieve Geofencing subscription information for a given subscription ID.
+      operationId: retrieveGeofencingSubscription
+      security:
+        - openId:
+            - geofencing-subscriptions:read
       parameters:
-        - $ref: '#/components/parameters/x-correlator'
-        - name: subscriptionsId
-          in: path
-          description: Subscription identifier that was obtained from the create event subscription operation
-          required: true
-          schema:
-            type: string
+        - $ref: "#/components/parameters/SubscriptionId"
+        - $ref: "#/components/parameters/x-correlator"
       responses:
         "200":
-          description: Contains information about Subscriptions
+          description: OK
           headers:
             x-correlator:
-              $ref: '#/components/headers/x-correlator'
+              $ref: "#/components/headers/x-correlator"
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/SubscriptionInfo"
+                $ref: "#/components/schemas/Subscription"
         "400":
-          $ref: "#/components/responses/Generic400"
+          $ref: "#/components/responses/SubscriptionIdRequired"
         "401":
           $ref: "#/components/responses/Generic401"
         "403":
@@ -242,32 +263,35 @@ paths:
           $ref: "#/components/responses/Generic500"
         "503":
           $ref: "#/components/responses/Generic503"
-      security:
-        - openId:
-            - geofencing-subscriptions:read
     delete:
       tags:
         - Geofencing subscriptions
-      summary: "Operation to delete a subscription"
-      operationId: deleteSubscription
-      description: Delete a given subscription by ID
-
+      summary: "Delete a Geofencing event subscription"
+      operationId: deleteGeofencingSubscription
+      description: delete a given Geofencing subscription.
+      security:
+        - openId:
+            - geofencing-subscriptions:delete
       parameters:
-        - $ref: '#/components/parameters/x-correlator'
-        - name: subscriptionsId
-          in: path
-          description: subscription identifier
-          required: true
-          schema:
-            type: string
+        - $ref: "#/components/parameters/SubscriptionId"
+        - $ref: "#/components/parameters/x-correlator"
       responses:
         "204":
-          description: Event subscription deleted
+          description: Geofencing subscription deleted
+          headers:
+            x-correlator:
+              $ref: "#/components/headers/x-correlator"
+        "202":
+          description: Request accepted to be processed. It applies for async deletion process.
           headers:
             x-correlator:
-              $ref: '#/components/headers/x-correlator'
+              $ref: "#/components/headers/x-correlator"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/SubscriptionAsync"
         "400":
-          $ref: "#/components/responses/Generic400"
+          $ref: "#/components/responses/SubscriptionIdRequired"
         "401":
           $ref: "#/components/responses/Generic401"
         "403":
@@ -278,16 +302,23 @@ paths:
           $ref: "#/components/responses/Generic500"
         "503":
           $ref: "#/components/responses/Generic503"
-      security:
-        - openId:
-            - geofencing-subscriptions:delete
-
 components:
   securitySchemes:
     openId:
       type: openIdConnect
       openIdConnectUrl: https://example.com/.well-known/openid-configuration
+    notificationsBearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: "{$request.body#/sinkCredential.credentialType}"
   parameters:
+    SubscriptionId:
+      name: subscriptionId
+      in: path
+      description: Subscription identifier that was obtained from the create event subscription operation
+      required: true
+      schema:
+        $ref: "#/components/schemas/SubscriptionId"
     x-correlator:
       name: x-correlator
       in: header
@@ -300,79 +331,305 @@ components:
       schema:
         type: string
   schemas:
-    Area:
+    ErrorInfo:
       type: object
+      required:
+        - status
+        - code
+        - message
       properties:
-        areaType:
-          $ref: "#/components/schemas/AreaType"
+        status:
+          type: integer
+          description: HTTP response status code
+        code:
+          type: string
+          description: Code given to this error
+        message:
+          type: string
+          description: Detailed error description
+
+    SubscriptionRequest:
+      description: The request for creating a event-type event subscription
+      type: object
       required:
-        - areaType
+        - sink
+        - protocol
+        - config
+        - types
+      properties:
+        protocol:
+          $ref: "#/components/schemas/Protocol"
+        sink:
+          type: string
+          format: url
+          description: The address to which events shall be delivered using the selected protocol.
+          example: "https://endpoint.example.com/sink"
+        sinkCredential:
+          allOf:
+            - description: A sink credential provides authentication or authorization information necessary to enable delivery of events to a target.
+            - $ref: "#/components/schemas/SinkCredential"
+        types:
+          description: |
+            Camara Event types eligible to be delivered by this subscription.
+            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.
+          type: array
+          items:
+            $ref: "#/components/schemas/SubscriptionEventType"
+        config:
+          $ref: "#/components/schemas/Config"
       discriminator:
-        propertyName: areaType
+        propertyName: protocol
         mapping:
-          CIRCLE: "#/components/schemas/Circle"
-
-    AreaType:
+          HTTP: "#/components/schemas/HTTPSubscriptionRequest"
+          MQTT3: "#/components/schemas/MQTTSubscriptionRequest"
+          MQTT5: "#/components/schemas/MQTTSubscriptionRequest"
+          AMQP: "#/components/schemas/AMQPSubscriptionRequest"
+          NATS: "#/components/schemas/NATSSubscriptionRequest"
+          KAFKA: "#/components/schemas/ApacheKafkaSubscriptionRequest"
+
+    Protocol:
       type: string
+      enum: ["HTTP", "MQTT3", "MQTT5", "AMQP", "NATS", "KAFKA"]
+      description: Identifier of a delivery protocol. Only HTTP is allowed for now
+      example: "HTTP"
+
+    Config:
       description: |
-        Type of this area.
-        CIRCLE - The area is defined as a circle.
-      enum:
-        - CIRCLE
+        Implementation-specific configuration parameters needed by the subscription manager for acquiring events.
+        In CAMARA we have predefined attributes like `subscriptionExpireTime`, `subscriptionMaxEvents`, `initialEvent`
+        Specific event type attributes must be defined in `subscriptionDetail`
+        Note: if a request is performed for several event type, all subscribed event will use same `config` parameters.
+      type: object
+      required:
+        - subscriptionDetail
+      properties:
+        subscriptionDetail:
+          $ref: "#/components/schemas/CreateSubscriptionDetail"
+        subscriptionExpireTime:
+          type: string
+          format: date-time
+          example: 2023-01-17T13:18:23.682Z
+          description: The subscription expiration time (in date-time format) requested by the API consumer. Up to API project decision to keep it.
+        subscriptionMaxEvents:
+          type: integer
+          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
+          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 area entered event. If consumer sets initialEvent to true and device is already in the geofence, an event is triggered
 
-    Circle:
-      description: Circular area
+    SinkCredential:
+      type: object
+      properties:
+        credentialType:
+          type: string
+          enum:
+            - PLAIN
+            - ACCESSTOKEN
+            - REFRESHTOKEN
+          description: "The type of the credential."
+      discriminator:
+        propertyName: credentialType
+        mapping:
+          PLAIN: "#/components/schemas/PlainCredential"
+          ACCESSTOKEN: "#/components/schemas/AccessTokenCredential"
+          REFRESHTOKEN: "#/components/schemas/RefreshTokenCredential"
+      required:
+        - credentialType
+    PlainCredential:
+      type: object
+      description: A plain credential as a combination of an identifier and a secret.
       allOf:
-        - $ref: "#/components/schemas/Area"
+        - $ref: "#/components/schemas/SinkCredential"
         - type: object
+          required:
+            - identifier
+            - secret
           properties:
-            center:
-              $ref: "#/components/schemas/Point"
-            radius:
-              type: integer
-              description: Expected accuracy for the subscription event of device location in m, from location (radius)
-              minimum: 2000
-              maximum: 200000
+            identifier:
+              description: The identifier might be an account or username.
+              type: string
+            secret:
+              description: The secret might be a password or passphrase.
+              type: string
+    AccessTokenCredential:
+      type: object
+      description: An access token credential.
+      allOf:
+        - $ref: "#/components/schemas/SinkCredential"
+        - type: object
+          properties:
+            accessToken:
+              description: REQUIRED. An access token is a previously acquired token granting access to the target resource.
+              type: string
+            accessTokenExpiresUtc:
+              type: string
+              format: date-time
+              description: REQUIRED. An absolute UTC instant at which the token shall be considered expired.
+            accessTokenType:
+              description: REQUIRED. Type of the access token (See [OAuth 2.0](https://tools.ietf.org/html/rfc6749#section-7.1)).
+              type: string
+              enum:
+                - bearer
           required:
-            - center
-            - radius
-      example:
-        areaType: CIRCLE
-        center:
-          latitude: 50.735851
-          longitude: 7.10066
-        radius: 50000
-
-    Point:
+            - accessToken
+            - accessTokenExpiresUtc
+            - accessTokenType
+    RefreshTokenCredential:
       type: object
-      description: Coordinates (latitude, longitude) defining a location in a map
+      description: An access token credential with a refresh token.
+      allOf:
+        - $ref: "#/components/schemas/SinkCredential"
+        - type: object
+          properties:
+            accessToken:
+              description: REQUIRED. An access token is a previously acquired token granting access to the target resource.
+              type: string
+            accessTokenExpiresUtc:
+              type: string
+              format: date-time
+              description: REQUIRED. An absolute UTC instant at which the token shall be considered expired.
+            accessTokenType:
+              description: REQUIRED. Type of the access token (See [OAuth 2.0](https://tools.ietf.org/html/rfc6749#section-7.1)).
+              type: string
+              enum:
+                - bearer
+            refreshToken:
+              description: REQUIRED. An refresh token credential used to acquire access tokens.
+              type: string
+            refreshTokenEndpoint:
+              type: string
+              format: uri
+              description: REQUIRED. A URL at which the refresh token can be traded for an access token.
       required:
-        - latitude
-        - longitude
+        - accessToken
+        - accessTokenExpiresUtc
+        - accessTokenType
+        - refreshToken
+        - refreshTokenEndpoint
+
+    SubscriptionDetail:
+      description: The detail of the requested event subscription
+      type: object
+
+    CreateSubscriptionDetail:
+      description: The detail of the requested event subscription
+      type: object
       properties:
-        latitude:
-          $ref: "#/components/schemas/Latitude"
-        longitude:
-          $ref: "#/components/schemas/Longitude"
-      example:
-        latitude: 50.735851
-        longitude: 7.10066
+        device:
+          $ref: "#/components/schemas/Device"
+        area:
+          $ref: "#/components/schemas/Area"
+        type:
+          $ref: "#/components/schemas/SubscriptionEventType"
+      required:
+        - device
+        - area
+        - type
 
-    Latitude:
-      description: Latitude component of a location
-      type: number
-      format: double
-      minimum: -90
-      maximum: 90
-      example: 50.735851
+    SubscriptionEventType:
+      type: string
+      description: |
+        area-entered - Event triggered when the device enters the given area
 
-    Longitude:
-      description: Longitude component of location
-      type: number
-      format: double
-      minimum: -180
-      maximum: 180
-      example: 7.10066
+        area-left - Event triggered when the device leaves the given area
+      enum:
+        - org.camaraproject.geofencing-subscriptions.v0.area-entered
+        - org.camaraproject.geofencing-subscriptions.v0.area-left
+
+    NotificationEventType:
+      type: string
+      description: |
+        area-entered - Event triggered when the device enters the given area
+
+        area-left - Event triggered when the device leaves the given area
+
+        subscription-ends - Event triggered when the subscription ends
+      enum:
+        - org.camaraproject.geofencing-subscriptions.v0.area-entered
+        - org.camaraproject.geofencing-subscriptions.v0.area-left
+        - org.camaraproject.geofencing-subscriptions.v0.subscription-ends
+
+    Subscription:
+      description: Represents a event-type subscription.
+      type: object
+      required:
+        - sink
+        - protocol
+        - config
+        - types
+        - id
+        - startsAt
+      properties:
+        protocol:
+          $ref: "#/components/schemas/Protocol"
+        sink:
+          type: string
+          format: url
+          description: The address to which events shall be delivered using the selected protocol.
+          example: "https://endpoint.example.com/sink"
+        sinkCredential:
+          $ref: '#/components/schemas/SinkCredential'
+        types:
+          description: |
+            Camara Event types eligible to be delivered by this subscription.
+          type: array
+          items:
+            type: string
+        config:
+          $ref: '#/components/schemas/Config'
+        id:
+          type: string
+          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: '1119920371'
+        startsAt:
+          type: string
+          format: date-time
+          description: Date when the event subscription will begin/began
+        expiresAt:
+          type: string
+          format: date-time
+          description: Date when the event subscription will expire. Only provided when `subscriptionExpireTime` is indicated by API client or Telco Operator has specific policy about that.
+        status:
+          type: string
+          description: |-
+            Current status of the subscription - Management of Subscription State engine is not mandatory for now. Note not all statuses may be considered to be implemented. Details:
+              - `ACTIVATION_REQUESTED`: Subscription creation (POST) is triggered but subscription creation process is not finished yet.
+              - `ACTIVE`: Subscription creation process is completed. Subscription is fully operative.
+              - `DEACTIVE`: Subscription is temporarily inactive, but its workflow logic is not deleted.
+              - `EXPIRED`: Subscription is ended (no longer active). This status applies when subscription is ended due to `SUBSCRIPTION_EXPIRED` or `ACCESS_TOKEN_EXPIRED` event.
+              - `DELETED`: Subscription is ended as deleted (no longer active). This status applies when subscription information is kept (i.e. subscription workflow is no longer active but its metainformation is kept).
+          enum:
+            - ACTIVATION_REQUESTED
+            - ACTIVE
+            - EXPIRED
+            - DEACTIVE
+            - DELETED
+      discriminator:
+        propertyName: protocol
+        mapping:
+          HTTP: '#/components/schemas/HTTPSubscriptionResponse'
+          MQTT3: '#/components/schemas/MQTTSubscriptionResponse'
+          MQTT5: '#/components/schemas/MQTTSubscriptionResponse'
+          AMQP: '#/components/schemas/AMQPSubscriptionResponse'
+          NATS: '#/components/schemas/NATSSubscriptionResponse'
+          KAFKA: '#/components/schemas/ApacheKafkaSubscriptionResponse'
+
+    SubscriptionAsync:
+      description: Response for a event-type subscription request managed asynchronously (Creation or Deletion)
+      type: object
+      properties:
+        id:
+          $ref: "#/components/schemas/SubscriptionId"
+
+    SubscriptionId:
+      type: string
+      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
 
     Device:
       description: |
@@ -427,8 +684,8 @@ components:
         publicPort:
           $ref: "#/components/schemas/Port"
       anyOf:
-        - required: [publicAddress, privateAddress]
-        - required: [publicAddress, publicPort]
+        - required: [ publicAddress, privateAddress ]
+        - required: [ publicAddress, publicPort ]
       example:
         publicAddress: "84.125.93.10"
         publicPort: 59765
@@ -452,174 +709,111 @@ components:
       format: ipv6
       example: 2001:db8:85a3:8d3:1319:8a2e:370:7344
 
-    ErrorInfo:
-      type: object
-      required:
-        - status
-        - code
-        - message
-      properties:
-        status:
-          type: integer
-          description: HTTP status code returned along with this error response
-        code:
-          type: string
-          description: Code given to this error
-        message:
-          type: string
-          description: Detailed error description
-
-    Webhook:
+    Area:
       type: object
-      description: Detail for event channel
       properties:
-        notificationUrl:
-          $ref: "#/components/schemas/NotificationUrl"
-        notificationAuthToken:
-          $ref: "#/components/schemas/NotificationAuthToken"
+        areaType:
+          $ref: "#/components/schemas/AreaType"
       required:
-        - notificationUrl
+        - areaType
+      discriminator:
+        propertyName: areaType
+        mapping:
+          CIRCLE: "#/components/schemas/Circle"
 
-    SubscriptionId:
-      type: string
-      format: uuid
-      description: Identifier of the event subscription - This attribute must not be present in the POST request as it is provided by API server
-
-    SubscriptionDetail:
-      type: object
-      description: Subscription detail
-      properties:
-        device:
-          $ref: "#/components/schemas/Device"
-        area:
-          $ref: "#/components/schemas/Area"
-        type:
-          $ref: "#/components/schemas/SubscriptionEventType"
-      required:
-        - device
-        - area
-        - type
-
-    SubscriptionEventType:
-      type: string
-      description: |
-        area-entered - Event triggered when the device enters the given area
-
-        area-left - Event triggered when the device leaves the given area
-      enum:
-        - org.camaraproject.geofencing-subscriptions.v0.area-entered
-        - org.camaraproject.geofencing-subscriptions.v0.area-left
-
-    NotificationEventType:
+    AreaType:
       type: string
       description: |
-        area-entered - Event triggered when the device enters the given area
-
-        area-left - Event triggered when the device leaves the given area
-
-        subscription-ends - Event triggered when the subscription ends
+        Type of this area.
+        CIRCLE - The area is defined as a circle.
       enum:
-        - org.camaraproject.geofencing-subscriptions.v0.area-entered
-        - org.camaraproject.geofencing-subscriptions.v0.area-left
-        - org.camaraproject.geofencing-subscriptions.v0.subscription-ends
-
-    NotificationUrl:
-      type: string
-      example: "https://application-server.com"
-      description: https callback address where the event notification must be POST-ed
-
-    NotificationAuthToken:
-      type: string
-      example: "c8974e592c2fa383d4a3960714"
-      description: "OAuth2 token to be used by the callback API endpoint. It MUST be indicated within HTTP Authorization header e.g. Authorization: Bearer $notificationAuthToken"
-
-    CreateSubscription:
-      description: The request for creating a geofencing subscription
-      type: object
-      properties:
-        webhook:
-          $ref: "#/components/schemas/Webhook"
-        subscriptionDetail:
-          $ref: "#/components/schemas/SubscriptionDetail"
-        subscriptionExpireTime:
-          type: string
-          format: date-time
-          description: The date time when the location-tracking has to be terminated.
-            It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone.
-            Recommended format is yyyy-MM-dd'T'HH:mm:ss.SSSZ (i.e. which allows 2023-07-03T14:27:08.312+02:00 or 2023-07-03T12:27:08.312Z)
-        subscriptionMaxEvents:
-          type: integer
-          description: Identifies the maximum number of event reports to be generated (>=1) - Once this number is reached, the subscription ends.
-          minimum: 1
-          example: 5
-      required:
-        - webhook
-        - subscriptionDetail
+        - CIRCLE
 
-    SubscriptionInfo:
-      description: Represents a geofencing event subscription.
-      type: object
+    Circle:
+      description: Circular area
       allOf:
-        - $ref: "#/components/schemas/CreateSubscription"
+        - $ref: "#/components/schemas/Area"
         - type: object
           properties:
-            subscriptionId:
-              $ref: "#/components/schemas/SubscriptionId"
-            startsAt:
-              type: string
-              format: date-time
-              description: The date time when the subscription started.
-                It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone.
-                Recommended format is yyyy-MM-dd'T'HH:mm:ss.SSSZ (i.e. which allows 2023-07-03T14:27:08.312+02:00 or 2023-07-03T12:27:08.312Z)
-            expiresAt:
-              type: string
-              format: date-time
-              description: The date time when the subscription will expire or expired.
-                It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone.
-                Recommended format is yyyy-MM-dd'T'HH:mm:ss.SSSZ (i.e. which allows 2023-07-03T14:27:08.312+02:00 or 2023-07-03T12:27:08.312Z)
+            center:
+              $ref: "#/components/schemas/Point"
+            radius:
+              type: integer
+              description: Expected accuracy for the subscription event of device location in m, from location (radius)
+              minimum: 2000
+              maximum: 200000
           required:
-            - subscriptionId
+            - center
+            - radius
+      example:
+        areaType: CIRCLE
+        center:
+          latitude: 50.735851
+          longitude: 7.10066
+        radius: 50000
 
-    EventTime:
-      format: date-time
-      type: string
-      description: |
-        Timestamp of when the occurrence happened.
-        If the time of the occurrence cannot be determined then this attribute MAY be set to some other time (such as the current time) by the CloudEvents producer,
-        however all producers for the same source MUST be consistent in this respect. In other words,
-        either they all use the actual time of the occurrence or they all use the same algorithm to determine the value used.
-        It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone.
-        Recommended format is yyyy-MM-dd'T'HH:mm:ss.SSSZ (i.e. which allows 2023-07-03T14:27:08.312+02:00 or 2023-07-03T12:27:08.312Z)
+    Point:
+      type: object
+      description: Coordinates (latitude, longitude) defining a location in a map
+      required:
+        - latitude
+        - longitude
+      properties:
+        latitude:
+          $ref: "#/components/schemas/Latitude"
+        longitude:
+          $ref: "#/components/schemas/Longitude"
+      example:
+        latitude: 50.735851
+        longitude: 7.10066
+
+    Latitude:
+      description: Latitude component of a location
+      type: number
+      format: double
+      minimum: -90
+      maximum: 90
+      example: 50.735851
+
+    Longitude:
+      description: Longitude component of location
+      type: number
+      format: double
+      minimum: -180
+      maximum: 180
+      example: 7.10066
 
     CloudEvent:
-      description: The Cloud-Event used for the callback.
-      type: object
+      description: The notification callback
       required:
         - id
         - source
-        - type
         - specversion
+        - type
         - time
       properties:
         id:
-          description: Identifier of this event, that must be unique in the source context.
           type: string
+          description: identifier of this event, that must be unique in the source context.
         source:
           $ref: "#/components/schemas/Source"
         type:
           $ref: "#/components/schemas/NotificationEventType"
         specversion:
-          description: Version of the specification to which this event conforms (must be 1.0 if it conforms to cloudevents 1.0.2 version)
           type: string
+          description: Version of the specification to which this event conforms (must be 1.0 if it conforms to cloudevents 1.0.2 version)
           enum:
             - "1.0"
         datacontenttype:
-          description: 'media-type that describes the event payload encoding, must be "application/json" for CAMARA APIs'
           type: string
+          description: 'media-type that describes the event payload encoding, must be "application/json" for CAMARA APIs'
           enum:
             - application/json
+        data:
+          type: object
+          description: Event details payload described in each CAMARA API and referenced by its type
         time:
-          $ref: "#/components/schemas/EventTime"
+          $ref: "#/components/schemas/DateTime"
       discriminator:
         propertyName: "type"
         mapping:
@@ -627,13 +821,33 @@ components:
           org.camaraproject.geofencing-subscriptions.v0.area-entered: "#/components/schemas/EventAreaEntered"
           org.camaraproject.geofencing-subscriptions.v0.subscription-ends: "#/components/schemas/EventSubscriptionEnds"
 
+    Source:
+      type: string
+      format: uri-reference
+      minLength: 1
+      description: |
+        Identifies the context in which an event happened - be a non-empty `URI-reference` like:
+        - URI with a DNS authority:
+          * https://github.com/cloudevents
+          * mailto:cncf-wg-serverless@lists.cncf.io
+        - Universally-unique URN with a UUID:
+          * urn:uuid:6e8bc430-9c3a-11d9-9669-0800200c9a66
+        - Application-specific identifier:
+          * /cloudevents/spec/pull/123
+          * 1-555-123-4567
+      example: "https://notificationSendServer12.supertelco.com"
+
+    DateTime:
+      type: string
+      format: date-time
+      description: Timestamp of when the occurrence happened. Must adhere to RFC 3339.
+      example: "2018-04-05T17:31:00Z"
+
     EventAreaLeft:
       description: event structure for event when the device leaves the area
       allOf:
         - $ref: "#/components/schemas/CloudEvent"
         - type: object
-          required:
-            - data
           properties:
             data:
               $ref: "#/components/schemas/AreaLeft"
@@ -643,8 +857,6 @@ components:
       allOf:
         - $ref: "#/components/schemas/CloudEvent"
         - type: object
-          required:
-            - data
           properties:
             data:
               $ref: "#/components/schemas/AreaEntered"
@@ -654,8 +866,6 @@ components:
       allOf:
         - $ref: "#/components/schemas/CloudEvent"
         - type: object
-          required:
-            - data
           properties:
             data:
               $ref: "#/components/schemas/SubscriptionEnds"
@@ -708,81 +918,266 @@ components:
         subscriptionId:
           $ref: "#/components/schemas/SubscriptionId"
 
-    Source:
-      type: string
-      format: uri-reference
-      minLength: 1
-      description: |
-        Identifies the context in which an event happened, as a non-empty `URI-reference` like:
-        - URI with a DNS authority:
-          * https://github.com/cloudevents
-          * mailto:cncf-wg-serverless@lists.cncf.io
-        - Universally-unique URN with a UUID:
-          * urn:uuid:6e8bc430-9c3a-11d9-9669-0800200c9a66
-        - Application-specific identifier:
-          * /cloudevents/spec/pull/123
-          * 1-555-123-4567
-      example: "https://notificationSendServer12.supertelco.com"
-
     TerminationReason:
       type: string
       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
+        - 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
       enum:
         - MAX_EVENTS_REACHED
         - NETWORK_TERMINATED
         - SUBSCRIPTION_EXPIRED
+        - ACCESS_TOKEN_EXPIRED
+
+    HTTPSubscriptionRequest:
+      allOf:
+        - $ref: "#/components/schemas/SubscriptionRequest"
+        - type: object
+          properties:
+            protocolSettings:
+              $ref: "#/components/schemas/HTTPSettings"
+
+    HTTPSubscriptionResponse:
+      allOf:
+        - $ref: "#/components/schemas/Subscription"
+        - type: object
+          properties:
+            protocolSettings:
+              $ref: "#/components/schemas/HTTPSettings"
+
+    HTTPSettings:
+      type: object
+      properties:
+        headers:
+          type: object
+          description: |-
+            A set of key/value pairs that is copied into the HTTP request as custom headers.
+
+            NOTE: Use/Applicability of this concept has not been discussed in Commonalities under the scope of Meta Release v0.4. When required by an API project as an option to meet a UC/Requirement, please generate an issue for Commonalities discussion about it.
+          additionalProperties:
+            type: string
+        method:
+          type: string
+          description: The HTTP method to use for sending the message.
+          enum:
+            - POST
+
+    MQTTSubscriptionRequest:
+      allOf:
+        - $ref: "#/components/schemas/SubscriptionRequest"
+        - type: object
+          properties:
+            protocolSettings:
+              $ref: "#/components/schemas/MQTTSettings"
+
+    MQTTSubscriptionResponse:
+      allOf:
+        - $ref: "#/components/schemas/Subscription"
+        - type: object
+          properties:
+            protocolSettings:
+              $ref: "#/components/schemas/MQTTSettings"
+
+    MQTTSettings:
+      type: object
+      properties:
+        topicName:
+          type: string
+        qos:
+          type: integer
+          format: int32
+        retain:
+          type: boolean
+        expiry:
+          type: integer
+          format: int32
+        userProperties:
+          type: object
+      required:
+        - topicName
+
+    AMQPSubscriptionRequest:
+      allOf:
+        - $ref: "#/components/schemas/SubscriptionRequest"
+        - type: object
+          properties:
+            protocolSettings:
+              $ref: "#/components/schemas/AMQPSettings"
+
+    AMQPSubscriptionResponse:
+      allOf:
+        - $ref: "#/components/schemas/Subscription"
+        - type: object
+          properties:
+            protocolSettings:
+              $ref: "#/components/schemas/AMQPSettings"
+
+    AMQPSettings:
+      type: object
+      properties:
+        address:
+          type: string
+        linkName:
+          type: string
+        senderSettlementMode:
+          type: string
+          enum: ["settled", "unsettled"]
+        linkProperties:
+          type: object
+          additionalProperties:
+            type: string
+
+    ApacheKafkaSubscriptionRequest:
+      allOf:
+        - $ref: "#/components/schemas/SubscriptionRequest"
+        - type: object
+          properties:
+            protocolSettings:
+              $ref: "#/components/schemas/ApacheKafkaSettings"
+
+    ApacheKafkaSubscriptionResponse:
+      allOf:
+        - $ref: "#/components/schemas/Subscription"
+        - type: object
+          properties:
+            protocolSettings:
+              $ref: "#/components/schemas/ApacheKafkaSettings"
+
+    ApacheKafkaSettings:
+      type: object
+      properties:
+        topicName:
+          type: string
+        partitionKeyExtractor:
+          type: string
+        clientId:
+          type: string
+        ackMode:
+          type: integer
+      required:
+        - topicName
+
+    NATSSubscriptionRequest:
+      allOf:
+        - $ref: "#/components/schemas/SubscriptionRequest"
+        - type: object
+          properties:
+            protocolSettings:
+              $ref: "#/components/schemas/NATSSettings"
+
+    NATSSubscriptionResponse:
+      allOf:
+        - $ref: "#/components/schemas/Subscription"
+        - type: object
+          properties:
+            protocolSettings:
+              $ref: "#/components/schemas/NATSSettings"
 
+    NATSSettings:
+      type: object
+      properties:
+        subject:
+          type: string
+      required:
+        - subject
   responses:
+    CreateSubscriptionBadRequest400:
+      description: Problem with the client request
+      headers:
+        x-correlator:
+          $ref: "#/components/headers/x-correlator"
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/ErrorInfo"
+          examples:
+            InvalidArgument:
+              value:
+                status: 400
+                code: "INVALID_ARGUMENT"
+                message: "Client specified an invalid argument, request body or query param"
+            InvalidProtocol:
+              value:
+                status: 400
+                code: "INVALID_PROTOCOL"
+                message: "Only HTTP is supported"
+            InvalidCredential:
+              value:
+                status: 400
+                code: "INVALID_CREDENTIAL"
+                message: "Only Access token is supported"
+            InvalidToken:
+              value:
+                status: 400
+                code: "INVALID_TOKEN"
+                message: "Only bearer token is supported"
     Generic400:
-      description: Invalid argument
+      description: Problem with the client request
       headers:
         x-correlator:
-          $ref: '#/components/headers/x-correlator'
+          $ref: "#/components/headers/x-correlator"
       content:
         application/json:
           schema:
             $ref: "#/components/schemas/ErrorInfo"
           example:
             status: 400
-            code: INVALID_ARGUMENT
-            message: "Invalid argument"
-
+            code: "INVALID_ARGUMENT"
+            message: "Client specified an invalid argument, request body or query param"
     Generic401:
-      description: Unauthenticated
+      description: Authentication problem with the client request
       headers:
         x-correlator:
-          $ref: '#/components/headers/x-correlator'
+          $ref: "#/components/headers/x-correlator"
       content:
         application/json:
           schema:
             $ref: "#/components/schemas/ErrorInfo"
           example:
             status: 401
-            code: UNAUTHENTICATED
-            message: "Authorization failed: ..."
+            code: "UNAUTHENTICATED"
+            message: "Request not authenticated due to missing, invalid, or expired credentials"
 
+    CreateSubscription403:
+      description: Client does not have sufficient permission
+      headers:
+        x-correlator:
+          $ref: "#/components/headers/x-correlator"
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/ErrorInfo"
+          examples:
+            PermissionDenied:
+              value:
+                status: 403
+                code: "PERMISSION_DENIED"
+                message: "Client does not have sufficient permissions to perform this action"
+            TokenMismatch:
+              value:
+                status: 403
+                code: "SUSBCRIPTION_MISMATCH"
+                message: "Inconsistent access token for requested events subscription"
     Generic403:
-      description: Permission denied
+      description: Client does not have sufficient permission
       headers:
         x-correlator:
-          $ref: '#/components/headers/x-correlator'
+          $ref: "#/components/headers/x-correlator"
       content:
         application/json:
           schema:
             $ref: "#/components/schemas/ErrorInfo"
           example:
             status: 403
-            code: PERMISSION_DENIED
-            message: "Operation not allowed: ..."
-
+            code: "PERMISSION_DENIED"
+            message: "Client does not have sufficient permissions to perform this action"
     Generic404:
-      description: Not found
+      description: Resource Not Found
       headers:
         x-correlator:
-          $ref: '#/components/headers/x-correlator'
+          $ref: "#/components/headers/x-correlator"
       content:
         application/json:
           schema:
@@ -791,66 +1186,140 @@ components:
             status: 404
             code: NOT_FOUND
             message: "The specified resource is not found"
-
     Generic409:
       description: Conflict
       headers:
         x-correlator:
-          $ref: '#/components/headers/x-correlator'
+          $ref: "#/components/headers/x-correlator"
       content:
         application/json:
           schema:
             $ref: "#/components/schemas/ErrorInfo"
           example:
             status: 409
-            code: Conflict
-            message: "There is conflict in the request"
-
+            code: CONFLICT
+            message: "The specified resource is in a conflict"
+    Generic410:
+      description: Gone
+      headers:
+        x-correlator:
+          $ref: "#/components/headers/x-correlator"
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/ErrorInfo"
+          example:
+            status: 410
+            code: GONE
+            message: "The specified resource is no longer available at the requested address"
+    Generic415:
+      description: Unsupported Media Type
+      headers:
+        X-Correlator:
+          $ref: "#/components/headers/x-correlator"
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/ErrorInfo"
+          example:
+            status: 415
+            code: UNSUPPORTED_MEDIA_TYPE
+            message: "The specified media type is not supported"
+    CreateSubscription422:
+      description: Unprocessable Entity
+      headers:
+        x-correlator:
+          $ref: "#/components/headers/x-correlator"
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/ErrorInfo"
+          examples:
+            PermissionDenied:
+              value:
+                status: 422
+                code: "MULTIEVENT_SUBSCRIPTION_NOT_SUPPORTED"
+                message: "Multi event types subscription not managed"
+    Generic429:
+      description: Too Many Requests
+      headers:
+        X-Correlator:
+          $ref: "#/components/headers/x-correlator"
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/ErrorInfo"
+          example:
+            status: 429
+            code: TOO_MANY_REQUESTS
+            message: "Endpoint does not support as many requests per time slot"
     Generic500:
-      description: Internal server error
+      description: Server error
       headers:
         x-correlator:
-          $ref: '#/components/headers/x-correlator'
+          $ref: "#/components/headers/x-correlator"
       content:
         application/json:
           schema:
             $ref: "#/components/schemas/ErrorInfo"
           example:
             status: 500
-            code: INTERNAL
-            message: "Internal server error"
-
+            code: "INTERNAL"
+            message: "Server error"
     Generic503:
-      description: Service unavailable
+      description: Service unavailable. Typically the server is down.
       headers:
         x-correlator:
-          $ref: '#/components/headers/x-correlator'
+          $ref: "#/components/headers/x-correlator"
       content:
         application/json:
           schema:
             $ref: "#/components/schemas/ErrorInfo"
           example:
             status: 503
-            code: UNAVAILABLE
+            code: "UNAVAILABLE"
             message: "Service unavailable"
-
-
+    SubscriptionIdRequired:
+      description: Problem with the client request
+      headers:
+        x-correlator:
+          $ref: "#/components/headers/x-correlator"
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/ErrorInfo"
+          examples:
+            Generic400:
+              summary: Schema validation failed
+              value:
+                status: 400
+                code: INVALID_ARGUMENT
+                message: "Client specified an invalid argument, request body or query param"
+            subscriptionIdRequired:
+              summary: subscription id is required
+              value:
+                status: 400
+                code: INVALID_ARGUMENT
+                message: "Expected property is missing: subscriptionId"
   examples:
     REQUEST_CIRCLE_AREA_ENTERED:
       value:
-        webhook:
-          notificationUrl: https://application-server.com
-          notificationAuthToken: c8974e592c2fa383d4a3960714
-        subscriptionDetail:
-          device:
-            phoneNumber: "+12345678912"
-          area:
-            areaType: CIRCLE
-            center:
-              latitude: 50.735851
-              longitude: 7.10066
-            radius: 2000
-          type: org.camaraproject.geofencing-subscriptions.v0.area-entered
+        protocol: "HTTP"
+        sink: https://notificationSendServer12.supertelco.com
+        types:
+          - org.camaraproject.geofencing-subscriptions.v0.area-entered
+        config:
+          subscriptionDetail:
+            device:
+              phoneNumber: "+12345678912"
+            area:
+              areaType: CIRCLE
+              center:
+                latitude: 50.735851
+                longitude: 7.10066
+              radius: 2000
+          initialEvent: "true"
+          subscriptionMaxEvents: 10
         subscriptionExpireTime: 2024-03-22T05:40:58.469Z
     CIRCLE_AREA_ENTERED:
       value:
@@ -901,4 +1370,4 @@ components:
           subscriptionId: 987654321
           device:
             phoneNumber: +123456789
-          terminationReason: SUBSCRIPTION_EXPIRED
+          terminationReason: SUBSCRIPTION_EXPIRED
\ No newline at end of file

From 10ad86a3ba20eefe9f7575cd94c57222ed5c9dd3 Mon Sep 17 00:00:00 2001
From: Maximilian Laue <Maximilian.Laue@t-systems.com>
Date: Thu, 6 Jun 2024 23:24:32 +0200
Subject: [PATCH 02/20] feat: update description

---
 code/API_definitions/geofencing-subscriptions.yaml | 2 --
 1 file changed, 2 deletions(-)

diff --git a/code/API_definitions/geofencing-subscriptions.yaml b/code/API_definitions/geofencing-subscriptions.yaml
index 2c1b87ae..2d5562c7 100644
--- a/code/API_definitions/geofencing-subscriptions.yaml
+++ b/code/API_definitions/geofencing-subscriptions.yaml
@@ -35,8 +35,6 @@ info:
     The CAMARA subscription model is detailed in the CAMARA API design guideline document and follows CloudEvents specification.
 
     It is mandatory in the subscription to provide the event `type` for which the client would like to subscribe.
-    
-    _Note: An array of types could be passed but as of now only one value MUST passed. Use of multiple value will be open later at API level._
 
 
     Following event ``type`` are managed for this API:

From f6f1ad2ee43f97ea87643cf51f526cace5920ac5 Mon Sep 17 00:00:00 2001
From: Maximilian Laue <Maximilian.Laue@t-systems.com>
Date: Thu, 6 Jun 2024 23:30:17 +0200
Subject: [PATCH 03/20] fix: use double-quotes

---
 .../geofencing-subscriptions.yaml             | 23 +++++++++----------
 1 file changed, 11 insertions(+), 12 deletions(-)

diff --git a/code/API_definitions/geofencing-subscriptions.yaml b/code/API_definitions/geofencing-subscriptions.yaml
index 2d5562c7..6aa7bf7a 100644
--- a/code/API_definitions/geofencing-subscriptions.yaml
+++ b/code/API_definitions/geofencing-subscriptions.yaml
@@ -36,7 +36,6 @@ info:
 
     It is mandatory in the subscription to provide the event `type` for which the client would like to subscribe.
 
-
     Following event ``type`` are managed for this API:
       - ``org.camaraproject.geofencing-subscriptions.v0.area-entered``  - Event triggered when the device enters the given area
 
@@ -93,7 +92,7 @@ paths:
       description: Create a subscription for a device to receive notifications when a device enters or exits a specified area
       operationId: createSubscription
       parameters:
-        - $ref: '#/components/parameters/x-correlator'
+        - $ref: "#/components/parameters/x-correlator"
       security:
         - openId:
             - geofencing-subscriptions:org.camaraproject.geofencing-subscriptions.v0.area-entered:create
@@ -215,7 +214,7 @@ paths:
                 type: array
                 minItems: 0
                 items:
-                  $ref: '#/components/schemas/Subscription'
+                  $ref: "#/components/schemas/Subscription"
         "400":
           $ref: "#/components/responses/Generic400"
         "401":
@@ -571,7 +570,7 @@ components:
           description: The address to which events shall be delivered using the selected protocol.
           example: "https://endpoint.example.com/sink"
         sinkCredential:
-          $ref: '#/components/schemas/SinkCredential'
+          $ref: "#/components/schemas/SinkCredential"
         types:
           description: |
             Camara Event types eligible to be delivered by this subscription.
@@ -579,11 +578,11 @@ components:
           items:
             type: string
         config:
-          $ref: '#/components/schemas/Config'
+          $ref: "#/components/schemas/Config"
         id:
           type: string
           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: '1119920371'
+          example: "1119920371"
         startsAt:
           type: string
           format: date-time
@@ -610,12 +609,12 @@ components:
       discriminator:
         propertyName: protocol
         mapping:
-          HTTP: '#/components/schemas/HTTPSubscriptionResponse'
-          MQTT3: '#/components/schemas/MQTTSubscriptionResponse'
-          MQTT5: '#/components/schemas/MQTTSubscriptionResponse'
-          AMQP: '#/components/schemas/AMQPSubscriptionResponse'
-          NATS: '#/components/schemas/NATSSubscriptionResponse'
-          KAFKA: '#/components/schemas/ApacheKafkaSubscriptionResponse'
+          HTTP: "#/components/schemas/HTTPSubscriptionResponse"
+          MQTT3: "#/components/schemas/MQTTSubscriptionResponse"
+          MQTT5: "#/components/schemas/MQTTSubscriptionResponse"
+          AMQP: "#/components/schemas/AMQPSubscriptionResponse"
+          NATS: "#/components/schemas/NATSSubscriptionResponse"
+          KAFKA: "#/components/schemas/ApacheKafkaSubscriptionResponse"
 
     SubscriptionAsync:
       description: Response for a event-type subscription request managed asynchronously (Creation or Deletion)

From 69e5959f09ae62b0f7423e0f114260a8ab209fd8 Mon Sep 17 00:00:00 2001
From: Maximilian Laue <Maximilian.Laue@t-systems.com>
Date: Thu, 6 Jun 2024 23:35:35 +0200
Subject: [PATCH 04/20] fix: MegaLinter issues

---
 code/API_definitions/geofencing-subscriptions.yaml | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/code/API_definitions/geofencing-subscriptions.yaml b/code/API_definitions/geofencing-subscriptions.yaml
index 6aa7bf7a..71ae0b2e 100644
--- a/code/API_definitions/geofencing-subscriptions.yaml
+++ b/code/API_definitions/geofencing-subscriptions.yaml
@@ -51,7 +51,7 @@ info:
 
     ### Notification callback
 
-    This endpoint describes the event notification received on subscription listener side when the event occurred. 
+    This endpoint describes the event notification received on subscription listener side when the event occurred.
     As for subscription, detailed description of the event notification is provided in the CAMARA API design guideline document.
 
     _**WARNING**: This callback endpoint must be exposed on the consumer side as `POST /{$request.body#/sink}`.
@@ -681,8 +681,8 @@ components:
         publicPort:
           $ref: "#/components/schemas/Port"
       anyOf:
-        - required: [ publicAddress, privateAddress ]
-        - required: [ publicAddress, publicPort ]
+        - required: [publicAddress, privateAddress]
+        - required: [publicAddress, publicPort]
       example:
         publicAddress: "84.125.93.10"
         publicPort: 59765
@@ -1367,4 +1367,4 @@ components:
           subscriptionId: 987654321
           device:
             phoneNumber: +123456789
-          terminationReason: SUBSCRIPTION_EXPIRED
\ No newline at end of file
+          terminationReason: SUBSCRIPTION_EXPIRED

From 740ebd9bcbf33d9b0dad9c03c2a4595236682586 Mon Sep 17 00:00:00 2001
From: Maximilian Laue <Maximilian.Laue@t-systems.com>
Date: Thu, 6 Jun 2024 23:42:02 +0200
Subject: [PATCH 05/20] fix: remove "type" from subscriptionDetail

---
 code/API_definitions/geofencing-subscriptions.yaml | 6 ++----
 1 file changed, 2 insertions(+), 4 deletions(-)

diff --git a/code/API_definitions/geofencing-subscriptions.yaml b/code/API_definitions/geofencing-subscriptions.yaml
index 71ae0b2e..077c6aec 100644
--- a/code/API_definitions/geofencing-subscriptions.yaml
+++ b/code/API_definitions/geofencing-subscriptions.yaml
@@ -193,7 +193,7 @@ paths:
           $ref: "#/components/responses/Generic503"
     get:
       tags:
-        - Geofencing Subscription
+        - Geofencing subscriptions
       summary: "Retrieve a list of geofencing event subscription"
       description: Retrieve a list of geofencing event subscription(s)
       operationId: retrieveGeofencingSubscriptionList
@@ -329,6 +329,7 @@ components:
         type: string
   schemas:
     ErrorInfo:
+      description: The error info object for possible error cases
       type: object
       required:
         - status
@@ -521,12 +522,9 @@ components:
           $ref: "#/components/schemas/Device"
         area:
           $ref: "#/components/schemas/Area"
-        type:
-          $ref: "#/components/schemas/SubscriptionEventType"
       required:
         - device
         - area
-        - type
 
     SubscriptionEventType:
       type: string

From 74181aeef221f07afac061e3c48e7686243323b7 Mon Sep 17 00:00:00 2001
From: Maximilian Laue <Maximilian.Laue@t-systems.com>
Date: Thu, 6 Jun 2024 23:52:58 +0200
Subject: [PATCH 06/20] feat: add descriptions for examples

---
 code/API_definitions/geofencing-subscriptions.yaml | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/code/API_definitions/geofencing-subscriptions.yaml b/code/API_definitions/geofencing-subscriptions.yaml
index 077c6aec..2235b70a 100644
--- a/code/API_definitions/geofencing-subscriptions.yaml
+++ b/code/API_definitions/geofencing-subscriptions.yaml
@@ -1298,6 +1298,7 @@ components:
                 message: "Expected property is missing: subscriptionId"
   examples:
     REQUEST_CIRCLE_AREA_ENTERED:
+      description: A sample geofence for entering for a circle area
       value:
         protocol: "HTTP"
         sink: https://notificationSendServer12.supertelco.com
@@ -1315,8 +1316,9 @@ components:
               radius: 2000
           initialEvent: "true"
           subscriptionMaxEvents: 10
-        subscriptionExpireTime: 2024-03-22T05:40:58.469Z
+          subscriptionExpireTime: 2024-03-22T05:40:58.469Z
     CIRCLE_AREA_ENTERED:
+      description: The cloud event when a geofence area was entered
       value:
         id: "123655"
         source: https://notificationSendServer12.supertelco.com
@@ -1335,6 +1337,7 @@ components:
               longitude: 7.10066
             radius: 2000
     CIRCLE_AREA_LEFT:
+      description: The cloud event when a geofence area was left
       value:
         id: "123655"
         source: https://notificationSendServer12.supertelco.com
@@ -1354,6 +1357,7 @@ components:
             radius: 2000
 
     SUBSCRIPTION_ENDS:
+      description: The cloud event when a geofence subscription ends
       value:
         id: "123655"
         source: https://notificationSendServer12.supertelco.com

From 11c241d9c4a78d953da106e14a39c10398cc47f9 Mon Sep 17 00:00:00 2001
From: Maximilian Laue <Maximilian.Laue@t-systems.com>
Date: Thu, 6 Jun 2024 23:55:01 +0200
Subject: [PATCH 07/20] fix: examples initialEvent to boolean

---
 code/API_definitions/geofencing-subscriptions.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/code/API_definitions/geofencing-subscriptions.yaml b/code/API_definitions/geofencing-subscriptions.yaml
index 2235b70a..9b166c36 100644
--- a/code/API_definitions/geofencing-subscriptions.yaml
+++ b/code/API_definitions/geofencing-subscriptions.yaml
@@ -1314,7 +1314,7 @@ components:
                 latitude: 50.735851
                 longitude: 7.10066
               radius: 2000
-          initialEvent: "true"
+          initialEvent: true
           subscriptionMaxEvents: 10
           subscriptionExpireTime: 2024-03-22T05:40:58.469Z
     CIRCLE_AREA_ENTERED:

From b9cae0b7cc392212df4b553c8ac239237cf295c9 Mon Sep 17 00:00:00 2001
From: Maximilian Laue <Maximilian.Laue@t-systems.com>
Date: Fri, 7 Jun 2024 09:09:16 +0200
Subject: [PATCH 08/20] fix: update request content-type for CloudEvents to
 'application/cloudevents+json'

---
 code/API_definitions/geofencing-subscriptions.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/code/API_definitions/geofencing-subscriptions.yaml b/code/API_definitions/geofencing-subscriptions.yaml
index 9b166c36..44307643 100644
--- a/code/API_definitions/geofencing-subscriptions.yaml
+++ b/code/API_definitions/geofencing-subscriptions.yaml
@@ -121,7 +121,7 @@ paths:
               requestBody:
                 required: true
                 content:
-                  application/json:
+                  application/cloudevents+json:
                     schema:
                       $ref: "#/components/schemas/CloudEvent"
                     examples:

From 66a87e0ccde80ecab8c1e81134cf8860ed4b738b Mon Sep 17 00:00:00 2001
From: Maximilian Laue <Maximilian.Laue@t-systems.com>
Date: Fri, 7 Jun 2024 10:50:57 +0200
Subject: [PATCH 09/20] fix: enforce only one item in "types" - array

---
 code/API_definitions/geofencing-subscriptions.yaml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/code/API_definitions/geofencing-subscriptions.yaml b/code/API_definitions/geofencing-subscriptions.yaml
index 44307643..493dff99 100644
--- a/code/API_definitions/geofencing-subscriptions.yaml
+++ b/code/API_definitions/geofencing-subscriptions.yaml
@@ -369,9 +369,9 @@ components:
         types:
           description: |
             Camara Event types eligible to be delivered by this subscription.
-            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.
+            Note: As of now we enforce to have only event type per subscription.
           type: array
+          maxItems: 1
           items:
             $ref: "#/components/schemas/SubscriptionEventType"
         config:

From 671be925bd65fdeb81af4ab0a5d9a80e2a901b31 Mon Sep 17 00:00:00 2001
From: Maximilian Laue <Maximilian.Laue@t-systems.com>
Date: Fri, 7 Jun 2024 11:11:22 +0200
Subject: [PATCH 10/20] fix: some improvements

---
 code/API_definitions/geofencing-subscriptions.yaml | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/code/API_definitions/geofencing-subscriptions.yaml b/code/API_definitions/geofencing-subscriptions.yaml
index 493dff99..5bb21c89 100644
--- a/code/API_definitions/geofencing-subscriptions.yaml
+++ b/code/API_definitions/geofencing-subscriptions.yaml
@@ -47,6 +47,7 @@ info:
     It is used when:
       - the subscription expire time (optionally set by the requester) has been reached
       - the maximum number of subscription events (optionally set by the requester) has been reached
+      - the Access Token sinkCredential (optionally set by the requester) expiration time has been reached
       - the API server has to stop sending notification prematurely
 
     ### Notification callback
@@ -408,10 +409,10 @@ components:
           type: string
           format: date-time
           example: 2023-01-17T13:18:23.682Z
-          description: The subscription expiration time (in date-time format) requested by the API consumer. Up to API project decision to keep it.
+          description: The subscription expiration time (in date-time format) requested by the API consumer.
         subscriptionMaxEvents:
           type: integer
-          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.
+          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.
           minimum: 1
           example: 5
         initialEvent:

From 104130c8037cffab17889e7503ad9f2130417910 Mon Sep 17 00:00:00 2001
From: Maximilian Laue <Maximilian.Laue@t-systems.com>
Date: Fri, 7 Jun 2024 14:46:06 +0200
Subject: [PATCH 11/20] fix: some improvements

---
 code/API_definitions/geofencing-subscriptions.yaml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/code/API_definitions/geofencing-subscriptions.yaml b/code/API_definitions/geofencing-subscriptions.yaml
index 5bb21c89..304b4913 100644
--- a/code/API_definitions/geofencing-subscriptions.yaml
+++ b/code/API_definitions/geofencing-subscriptions.yaml
@@ -598,7 +598,7 @@ components:
               - `ACTIVE`: Subscription creation process is completed. Subscription is fully operative.
               - `DEACTIVE`: Subscription is temporarily inactive, but its workflow logic is not deleted.
               - `EXPIRED`: Subscription is ended (no longer active). This status applies when subscription is ended due to `SUBSCRIPTION_EXPIRED` or `ACCESS_TOKEN_EXPIRED` event.
-              - `DELETED`: Subscription is ended as deleted (no longer active). This status applies when subscription information is kept (i.e. subscription workflow is no longer active but its metainformation is kept).
+              - `DELETED`: Subscription is ended as deleted (no longer active). This status applies when subscription information is kept (i.e. subscription workflow is no longer active but its meta-information is kept).
           enum:
             - ACTIVATION_REQUESTED
             - ACTIVE
@@ -1154,7 +1154,7 @@ components:
             TokenMismatch:
               value:
                 status: 403
-                code: "SUSBCRIPTION_MISMATCH"
+                code: "SUBSCRIPTION_MISMATCH"
                 message: "Inconsistent access token for requested events subscription"
     Generic403:
       description: Client does not have sufficient permission

From 6b457b434c8000a6a32d2ad12a06150f4bb99b86 Mon Sep 17 00:00:00 2001
From: Maximilian Laue <112983658+maxl2287@users.noreply.github.com>
Date: Wed, 12 Jun 2024 14:47:13 +0200
Subject: [PATCH 12/20] style: format sinkCredential

Co-authored-by: Jose Luis Urien <jlurien@gmail.com>
---
 code/API_definitions/geofencing-subscriptions.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/code/API_definitions/geofencing-subscriptions.yaml b/code/API_definitions/geofencing-subscriptions.yaml
index 304b4913..7f1a0186 100644
--- a/code/API_definitions/geofencing-subscriptions.yaml
+++ b/code/API_definitions/geofencing-subscriptions.yaml
@@ -47,7 +47,7 @@ info:
     It is used when:
       - the subscription expire time (optionally set by the requester) has been reached
       - the maximum number of subscription events (optionally set by the requester) has been reached
-      - the Access Token sinkCredential (optionally set by the requester) expiration time has been reached
+      - the Access Token `sinkCredential` (optionally set by the requester) expiration time has been reached
       - the API server has to stop sending notification prematurely
 
     ### Notification callback

From d78d394e7aaa731eed888b898e78df1e5ad5bcdb Mon Sep 17 00:00:00 2001
From: Maximilian Laue <Maximilian.Laue@t-systems.com>
Date: Wed, 12 Jun 2024 14:53:21 +0200
Subject: [PATCH 13/20] feat: remove unused protocolls and credentialTypes

---
 .../geofencing-subscriptions.yaml             | 194 +-----------------
 1 file changed, 6 insertions(+), 188 deletions(-)

diff --git a/code/API_definitions/geofencing-subscriptions.yaml b/code/API_definitions/geofencing-subscriptions.yaml
index 7f1a0186..295c60fd 100644
--- a/code/API_definitions/geofencing-subscriptions.yaml
+++ b/code/API_definitions/geofencing-subscriptions.yaml
@@ -381,15 +381,11 @@ components:
         propertyName: protocol
         mapping:
           HTTP: "#/components/schemas/HTTPSubscriptionRequest"
-          MQTT3: "#/components/schemas/MQTTSubscriptionRequest"
-          MQTT5: "#/components/schemas/MQTTSubscriptionRequest"
-          AMQP: "#/components/schemas/AMQPSubscriptionRequest"
-          NATS: "#/components/schemas/NATSSubscriptionRequest"
-          KAFKA: "#/components/schemas/ApacheKafkaSubscriptionRequest"
 
     Protocol:
       type: string
-      enum: ["HTTP", "MQTT3", "MQTT5", "AMQP", "NATS", "KAFKA"]
+      enum:
+        - "HTTP"
       description: Identifier of a delivery protocol. Only HTTP is allowed for now
       example: "HTTP"
 
@@ -404,7 +400,7 @@ components:
         - subscriptionDetail
       properties:
         subscriptionDetail:
-          $ref: "#/components/schemas/CreateSubscriptionDetail"
+          $ref: "#/components/schemas/SubscriptionDetail"
         subscriptionExpireTime:
           type: string
           format: date-time
@@ -427,34 +423,15 @@ components:
         credentialType:
           type: string
           enum:
-            - PLAIN
             - ACCESSTOKEN
-            - REFRESHTOKEN
           description: "The type of the credential."
       discriminator:
         propertyName: credentialType
         mapping:
-          PLAIN: "#/components/schemas/PlainCredential"
           ACCESSTOKEN: "#/components/schemas/AccessTokenCredential"
-          REFRESHTOKEN: "#/components/schemas/RefreshTokenCredential"
       required:
         - credentialType
-    PlainCredential:
-      type: object
-      description: A plain credential as a combination of an identifier and a secret.
-      allOf:
-        - $ref: "#/components/schemas/SinkCredential"
-        - type: object
-          required:
-            - identifier
-            - secret
-          properties:
-            identifier:
-              description: The identifier might be an account or username.
-              type: string
-            secret:
-              description: The secret might be a password or passphrase.
-              type: string
+
     AccessTokenCredential:
       type: object
       description: An access token credential.
@@ -478,46 +455,10 @@ components:
             - accessToken
             - accessTokenExpiresUtc
             - accessTokenType
-    RefreshTokenCredential:
-      type: object
-      description: An access token credential with a refresh token.
-      allOf:
-        - $ref: "#/components/schemas/SinkCredential"
-        - type: object
-          properties:
-            accessToken:
-              description: REQUIRED. An access token is a previously acquired token granting access to the target resource.
-              type: string
-            accessTokenExpiresUtc:
-              type: string
-              format: date-time
-              description: REQUIRED. An absolute UTC instant at which the token shall be considered expired.
-            accessTokenType:
-              description: REQUIRED. Type of the access token (See [OAuth 2.0](https://tools.ietf.org/html/rfc6749#section-7.1)).
-              type: string
-              enum:
-                - bearer
-            refreshToken:
-              description: REQUIRED. An refresh token credential used to acquire access tokens.
-              type: string
-            refreshTokenEndpoint:
-              type: string
-              format: uri
-              description: REQUIRED. A URL at which the refresh token can be traded for an access token.
-      required:
-        - accessToken
-        - accessTokenExpiresUtc
-        - accessTokenType
-        - refreshToken
-        - refreshTokenEndpoint
 
     SubscriptionDetail:
       description: The detail of the requested event subscription
       type: object
-
-    CreateSubscriptionDetail:
-      description: The detail of the requested event subscription
-      type: object
       properties:
         device:
           $ref: "#/components/schemas/Device"
@@ -596,24 +537,19 @@ components:
             Current status of the subscription - Management of Subscription State engine is not mandatory for now. Note not all statuses may be considered to be implemented. Details:
               - `ACTIVATION_REQUESTED`: Subscription creation (POST) is triggered but subscription creation process is not finished yet.
               - `ACTIVE`: Subscription creation process is completed. Subscription is fully operative.
-              - `DEACTIVE`: Subscription is temporarily inactive, but its workflow logic is not deleted.
+              - `INACTIVE`: Subscription is temporarily inactive, but its workflow logic is not deleted.
               - `EXPIRED`: Subscription is ended (no longer active). This status applies when subscription is ended due to `SUBSCRIPTION_EXPIRED` or `ACCESS_TOKEN_EXPIRED` event.
               - `DELETED`: Subscription is ended as deleted (no longer active). This status applies when subscription information is kept (i.e. subscription workflow is no longer active but its meta-information is kept).
           enum:
             - ACTIVATION_REQUESTED
             - ACTIVE
             - EXPIRED
-            - DEACTIVE
+            - INACTIVE
             - DELETED
       discriminator:
         propertyName: protocol
         mapping:
           HTTP: "#/components/schemas/HTTPSubscriptionResponse"
-          MQTT3: "#/components/schemas/MQTTSubscriptionResponse"
-          MQTT5: "#/components/schemas/MQTTSubscriptionResponse"
-          AMQP: "#/components/schemas/AMQPSubscriptionResponse"
-          NATS: "#/components/schemas/NATSSubscriptionResponse"
-          KAFKA: "#/components/schemas/ApacheKafkaSubscriptionResponse"
 
     SubscriptionAsync:
       description: Response for a event-type subscription request managed asynchronously (Creation or Deletion)
@@ -960,124 +896,6 @@ components:
           enum:
             - POST
 
-    MQTTSubscriptionRequest:
-      allOf:
-        - $ref: "#/components/schemas/SubscriptionRequest"
-        - type: object
-          properties:
-            protocolSettings:
-              $ref: "#/components/schemas/MQTTSettings"
-
-    MQTTSubscriptionResponse:
-      allOf:
-        - $ref: "#/components/schemas/Subscription"
-        - type: object
-          properties:
-            protocolSettings:
-              $ref: "#/components/schemas/MQTTSettings"
-
-    MQTTSettings:
-      type: object
-      properties:
-        topicName:
-          type: string
-        qos:
-          type: integer
-          format: int32
-        retain:
-          type: boolean
-        expiry:
-          type: integer
-          format: int32
-        userProperties:
-          type: object
-      required:
-        - topicName
-
-    AMQPSubscriptionRequest:
-      allOf:
-        - $ref: "#/components/schemas/SubscriptionRequest"
-        - type: object
-          properties:
-            protocolSettings:
-              $ref: "#/components/schemas/AMQPSettings"
-
-    AMQPSubscriptionResponse:
-      allOf:
-        - $ref: "#/components/schemas/Subscription"
-        - type: object
-          properties:
-            protocolSettings:
-              $ref: "#/components/schemas/AMQPSettings"
-
-    AMQPSettings:
-      type: object
-      properties:
-        address:
-          type: string
-        linkName:
-          type: string
-        senderSettlementMode:
-          type: string
-          enum: ["settled", "unsettled"]
-        linkProperties:
-          type: object
-          additionalProperties:
-            type: string
-
-    ApacheKafkaSubscriptionRequest:
-      allOf:
-        - $ref: "#/components/schemas/SubscriptionRequest"
-        - type: object
-          properties:
-            protocolSettings:
-              $ref: "#/components/schemas/ApacheKafkaSettings"
-
-    ApacheKafkaSubscriptionResponse:
-      allOf:
-        - $ref: "#/components/schemas/Subscription"
-        - type: object
-          properties:
-            protocolSettings:
-              $ref: "#/components/schemas/ApacheKafkaSettings"
-
-    ApacheKafkaSettings:
-      type: object
-      properties:
-        topicName:
-          type: string
-        partitionKeyExtractor:
-          type: string
-        clientId:
-          type: string
-        ackMode:
-          type: integer
-      required:
-        - topicName
-
-    NATSSubscriptionRequest:
-      allOf:
-        - $ref: "#/components/schemas/SubscriptionRequest"
-        - type: object
-          properties:
-            protocolSettings:
-              $ref: "#/components/schemas/NATSSettings"
-
-    NATSSubscriptionResponse:
-      allOf:
-        - $ref: "#/components/schemas/Subscription"
-        - type: object
-          properties:
-            protocolSettings:
-              $ref: "#/components/schemas/NATSSettings"
-
-    NATSSettings:
-      type: object
-      properties:
-        subject:
-          type: string
-      required:
-        - subject
   responses:
     CreateSubscriptionBadRequest400:
       description: Problem with the client request

From b42584df2a55fdbd2b1381b0d9029e24f0aaeb07 Mon Sep 17 00:00:00 2001
From: Maximilian Laue <Maximilian.Laue@t-systems.com>
Date: Wed, 12 Jun 2024 14:54:14 +0200
Subject: [PATCH 14/20] fix: remove notificationsBearerAuth from
 securitySchemes

---
 code/API_definitions/geofencing-subscriptions.yaml | 4 ----
 1 file changed, 4 deletions(-)

diff --git a/code/API_definitions/geofencing-subscriptions.yaml b/code/API_definitions/geofencing-subscriptions.yaml
index 295c60fd..7961bebc 100644
--- a/code/API_definitions/geofencing-subscriptions.yaml
+++ b/code/API_definitions/geofencing-subscriptions.yaml
@@ -305,10 +305,6 @@ components:
     openId:
       type: openIdConnect
       openIdConnectUrl: https://example.com/.well-known/openid-configuration
-    notificationsBearerAuth:
-      type: http
-      scheme: bearer
-      bearerFormat: "{$request.body#/sinkCredential.credentialType}"
   parameters:
     SubscriptionId:
       name: subscriptionId

From 6c5cf485059d88a61fcfab1109ef1b9c9a908978 Mon Sep 17 00:00:00 2001
From: Maximilian Laue <Maximilian.Laue@t-systems.com>
Date: Thu, 13 Jun 2024 15:14:32 +0200
Subject: [PATCH 15/20] Revert "feat: remove unused protocolls and
 credentialTypes"

This reverts commit d78d394e7aaa731eed888b898e78df1e5ad5bcdb.
---
 .../geofencing-subscriptions.yaml             | 194 +++++++++++++++++-
 1 file changed, 188 insertions(+), 6 deletions(-)

diff --git a/code/API_definitions/geofencing-subscriptions.yaml b/code/API_definitions/geofencing-subscriptions.yaml
index 7961bebc..81786b06 100644
--- a/code/API_definitions/geofencing-subscriptions.yaml
+++ b/code/API_definitions/geofencing-subscriptions.yaml
@@ -377,11 +377,15 @@ components:
         propertyName: protocol
         mapping:
           HTTP: "#/components/schemas/HTTPSubscriptionRequest"
+          MQTT3: "#/components/schemas/MQTTSubscriptionRequest"
+          MQTT5: "#/components/schemas/MQTTSubscriptionRequest"
+          AMQP: "#/components/schemas/AMQPSubscriptionRequest"
+          NATS: "#/components/schemas/NATSSubscriptionRequest"
+          KAFKA: "#/components/schemas/ApacheKafkaSubscriptionRequest"
 
     Protocol:
       type: string
-      enum:
-        - "HTTP"
+      enum: ["HTTP", "MQTT3", "MQTT5", "AMQP", "NATS", "KAFKA"]
       description: Identifier of a delivery protocol. Only HTTP is allowed for now
       example: "HTTP"
 
@@ -396,7 +400,7 @@ components:
         - subscriptionDetail
       properties:
         subscriptionDetail:
-          $ref: "#/components/schemas/SubscriptionDetail"
+          $ref: "#/components/schemas/CreateSubscriptionDetail"
         subscriptionExpireTime:
           type: string
           format: date-time
@@ -419,15 +423,34 @@ components:
         credentialType:
           type: string
           enum:
+            - PLAIN
             - ACCESSTOKEN
+            - REFRESHTOKEN
           description: "The type of the credential."
       discriminator:
         propertyName: credentialType
         mapping:
+          PLAIN: "#/components/schemas/PlainCredential"
           ACCESSTOKEN: "#/components/schemas/AccessTokenCredential"
+          REFRESHTOKEN: "#/components/schemas/RefreshTokenCredential"
       required:
         - credentialType
-
+    PlainCredential:
+      type: object
+      description: A plain credential as a combination of an identifier and a secret.
+      allOf:
+        - $ref: "#/components/schemas/SinkCredential"
+        - type: object
+          required:
+            - identifier
+            - secret
+          properties:
+            identifier:
+              description: The identifier might be an account or username.
+              type: string
+            secret:
+              description: The secret might be a password or passphrase.
+              type: string
     AccessTokenCredential:
       type: object
       description: An access token credential.
@@ -451,10 +474,46 @@ components:
             - accessToken
             - accessTokenExpiresUtc
             - accessTokenType
+    RefreshTokenCredential:
+      type: object
+      description: An access token credential with a refresh token.
+      allOf:
+        - $ref: "#/components/schemas/SinkCredential"
+        - type: object
+          properties:
+            accessToken:
+              description: REQUIRED. An access token is a previously acquired token granting access to the target resource.
+              type: string
+            accessTokenExpiresUtc:
+              type: string
+              format: date-time
+              description: REQUIRED. An absolute UTC instant at which the token shall be considered expired.
+            accessTokenType:
+              description: REQUIRED. Type of the access token (See [OAuth 2.0](https://tools.ietf.org/html/rfc6749#section-7.1)).
+              type: string
+              enum:
+                - bearer
+            refreshToken:
+              description: REQUIRED. An refresh token credential used to acquire access tokens.
+              type: string
+            refreshTokenEndpoint:
+              type: string
+              format: uri
+              description: REQUIRED. A URL at which the refresh token can be traded for an access token.
+      required:
+        - accessToken
+        - accessTokenExpiresUtc
+        - accessTokenType
+        - refreshToken
+        - refreshTokenEndpoint
 
     SubscriptionDetail:
       description: The detail of the requested event subscription
       type: object
+
+    CreateSubscriptionDetail:
+      description: The detail of the requested event subscription
+      type: object
       properties:
         device:
           $ref: "#/components/schemas/Device"
@@ -533,19 +592,24 @@ components:
             Current status of the subscription - Management of Subscription State engine is not mandatory for now. Note not all statuses may be considered to be implemented. Details:
               - `ACTIVATION_REQUESTED`: Subscription creation (POST) is triggered but subscription creation process is not finished yet.
               - `ACTIVE`: Subscription creation process is completed. Subscription is fully operative.
-              - `INACTIVE`: Subscription is temporarily inactive, but its workflow logic is not deleted.
+              - `DEACTIVE`: Subscription is temporarily inactive, but its workflow logic is not deleted.
               - `EXPIRED`: Subscription is ended (no longer active). This status applies when subscription is ended due to `SUBSCRIPTION_EXPIRED` or `ACCESS_TOKEN_EXPIRED` event.
               - `DELETED`: Subscription is ended as deleted (no longer active). This status applies when subscription information is kept (i.e. subscription workflow is no longer active but its meta-information is kept).
           enum:
             - ACTIVATION_REQUESTED
             - ACTIVE
             - EXPIRED
-            - INACTIVE
+            - DEACTIVE
             - DELETED
       discriminator:
         propertyName: protocol
         mapping:
           HTTP: "#/components/schemas/HTTPSubscriptionResponse"
+          MQTT3: "#/components/schemas/MQTTSubscriptionResponse"
+          MQTT5: "#/components/schemas/MQTTSubscriptionResponse"
+          AMQP: "#/components/schemas/AMQPSubscriptionResponse"
+          NATS: "#/components/schemas/NATSSubscriptionResponse"
+          KAFKA: "#/components/schemas/ApacheKafkaSubscriptionResponse"
 
     SubscriptionAsync:
       description: Response for a event-type subscription request managed asynchronously (Creation or Deletion)
@@ -892,6 +956,124 @@ components:
           enum:
             - POST
 
+    MQTTSubscriptionRequest:
+      allOf:
+        - $ref: "#/components/schemas/SubscriptionRequest"
+        - type: object
+          properties:
+            protocolSettings:
+              $ref: "#/components/schemas/MQTTSettings"
+
+    MQTTSubscriptionResponse:
+      allOf:
+        - $ref: "#/components/schemas/Subscription"
+        - type: object
+          properties:
+            protocolSettings:
+              $ref: "#/components/schemas/MQTTSettings"
+
+    MQTTSettings:
+      type: object
+      properties:
+        topicName:
+          type: string
+        qos:
+          type: integer
+          format: int32
+        retain:
+          type: boolean
+        expiry:
+          type: integer
+          format: int32
+        userProperties:
+          type: object
+      required:
+        - topicName
+
+    AMQPSubscriptionRequest:
+      allOf:
+        - $ref: "#/components/schemas/SubscriptionRequest"
+        - type: object
+          properties:
+            protocolSettings:
+              $ref: "#/components/schemas/AMQPSettings"
+
+    AMQPSubscriptionResponse:
+      allOf:
+        - $ref: "#/components/schemas/Subscription"
+        - type: object
+          properties:
+            protocolSettings:
+              $ref: "#/components/schemas/AMQPSettings"
+
+    AMQPSettings:
+      type: object
+      properties:
+        address:
+          type: string
+        linkName:
+          type: string
+        senderSettlementMode:
+          type: string
+          enum: ["settled", "unsettled"]
+        linkProperties:
+          type: object
+          additionalProperties:
+            type: string
+
+    ApacheKafkaSubscriptionRequest:
+      allOf:
+        - $ref: "#/components/schemas/SubscriptionRequest"
+        - type: object
+          properties:
+            protocolSettings:
+              $ref: "#/components/schemas/ApacheKafkaSettings"
+
+    ApacheKafkaSubscriptionResponse:
+      allOf:
+        - $ref: "#/components/schemas/Subscription"
+        - type: object
+          properties:
+            protocolSettings:
+              $ref: "#/components/schemas/ApacheKafkaSettings"
+
+    ApacheKafkaSettings:
+      type: object
+      properties:
+        topicName:
+          type: string
+        partitionKeyExtractor:
+          type: string
+        clientId:
+          type: string
+        ackMode:
+          type: integer
+      required:
+        - topicName
+
+    NATSSubscriptionRequest:
+      allOf:
+        - $ref: "#/components/schemas/SubscriptionRequest"
+        - type: object
+          properties:
+            protocolSettings:
+              $ref: "#/components/schemas/NATSSettings"
+
+    NATSSubscriptionResponse:
+      allOf:
+        - $ref: "#/components/schemas/Subscription"
+        - type: object
+          properties:
+            protocolSettings:
+              $ref: "#/components/schemas/NATSSettings"
+
+    NATSSettings:
+      type: object
+      properties:
+        subject:
+          type: string
+      required:
+        - subject
   responses:
     CreateSubscriptionBadRequest400:
       description: Problem with the client request

From d617f20bb67f9038e8d4e4f08cd7e47e0d843346 Mon Sep 17 00:00:00 2001
From: Maximilian Laue <Maximilian.Laue@t-systems.com>
Date: Thu, 13 Jun 2024 15:15:40 +0200
Subject: [PATCH 16/20] fix: renaming to SubscriptionDetail

---
 code/API_definitions/geofencing-subscriptions.yaml | 6 +-----
 1 file changed, 1 insertion(+), 5 deletions(-)

diff --git a/code/API_definitions/geofencing-subscriptions.yaml b/code/API_definitions/geofencing-subscriptions.yaml
index 81786b06..136160f1 100644
--- a/code/API_definitions/geofencing-subscriptions.yaml
+++ b/code/API_definitions/geofencing-subscriptions.yaml
@@ -400,7 +400,7 @@ components:
         - subscriptionDetail
       properties:
         subscriptionDetail:
-          $ref: "#/components/schemas/CreateSubscriptionDetail"
+          $ref: "#/components/schemas/SubscriptionDetail"
         subscriptionExpireTime:
           type: string
           format: date-time
@@ -510,10 +510,6 @@ components:
     SubscriptionDetail:
       description: The detail of the requested event subscription
       type: object
-
-    CreateSubscriptionDetail:
-      description: The detail of the requested event subscription
-      type: object
       properties:
         device:
           $ref: "#/components/schemas/Device"

From b11de50ec8e83a054aa21682641b9ffb0d274ef3 Mon Sep 17 00:00:00 2001
From: Maximilian Laue <Maximilian.Laue@t-systems.com>
Date: Mon, 17 Jun 2024 09:17:47 +0200
Subject: [PATCH 17/20] feat: set `minItems: 1`

---
 code/API_definitions/geofencing-subscriptions.yaml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/code/API_definitions/geofencing-subscriptions.yaml b/code/API_definitions/geofencing-subscriptions.yaml
index 136160f1..5a0262ab 100644
--- a/code/API_definitions/geofencing-subscriptions.yaml
+++ b/code/API_definitions/geofencing-subscriptions.yaml
@@ -368,6 +368,7 @@ components:
             Camara Event types eligible to be delivered by this subscription.
             Note: As of now we enforce to have only event type per subscription.
           type: array
+          minItems: 1
           maxItems: 1
           items:
             $ref: "#/components/schemas/SubscriptionEventType"

From d5b22fc518a4f7ed8a5656b3d1c17c9b7920f3d2 Mon Sep 17 00:00:00 2001
From: Maximilian Laue <Maximilian.Laue@t-systems.com>
Date: Mon, 17 Jun 2024 10:32:42 +0200
Subject: [PATCH 18/20] fix: set "data" to be mandatory for CloudEvents

---
 code/API_definitions/geofencing-subscriptions.yaml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/code/API_definitions/geofencing-subscriptions.yaml b/code/API_definitions/geofencing-subscriptions.yaml
index 5a0262ab..3374b53e 100644
--- a/code/API_definitions/geofencing-subscriptions.yaml
+++ b/code/API_definitions/geofencing-subscriptions.yaml
@@ -780,6 +780,7 @@ components:
         - specversion
         - type
         - time
+        - data
       properties:
         id:
           type: string

From ea431e3a882e15cf4dcc36b99b4e4e9c05040124 Mon Sep 17 00:00:00 2001
From: Maximilian Laue <Maximilian.Laue@t-systems.com>
Date: Tue, 18 Jun 2024 15:12:00 +0200
Subject: [PATCH 19/20] fix: change to INACTIVE status

---
 code/API_definitions/geofencing-subscriptions.yaml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/code/API_definitions/geofencing-subscriptions.yaml b/code/API_definitions/geofencing-subscriptions.yaml
index 3374b53e..0d05a7ce 100644
--- a/code/API_definitions/geofencing-subscriptions.yaml
+++ b/code/API_definitions/geofencing-subscriptions.yaml
@@ -589,14 +589,14 @@ components:
             Current status of the subscription - Management of Subscription State engine is not mandatory for now. Note not all statuses may be considered to be implemented. Details:
               - `ACTIVATION_REQUESTED`: Subscription creation (POST) is triggered but subscription creation process is not finished yet.
               - `ACTIVE`: Subscription creation process is completed. Subscription is fully operative.
-              - `DEACTIVE`: Subscription is temporarily inactive, but its workflow logic is not deleted.
+              - `INACTIVE`: Subscription is temporarily inactive, but its workflow logic is not deleted.
               - `EXPIRED`: Subscription is ended (no longer active). This status applies when subscription is ended due to `SUBSCRIPTION_EXPIRED` or `ACCESS_TOKEN_EXPIRED` event.
               - `DELETED`: Subscription is ended as deleted (no longer active). This status applies when subscription information is kept (i.e. subscription workflow is no longer active but its meta-information is kept).
           enum:
             - ACTIVATION_REQUESTED
             - ACTIVE
             - EXPIRED
-            - DEACTIVE
+            - INACTIVE
             - DELETED
       discriminator:
         propertyName: protocol

From 7c1ff450a6f213b14156d00b62031364eeb0c84c Mon Sep 17 00:00:00 2001
From: Maximilian Laue <Maximilian.Laue@t-systems.com>
Date: Tue, 18 Jun 2024 15:25:59 +0200
Subject: [PATCH 20/20] fix: update "types" in description

---
 code/API_definitions/geofencing-subscriptions.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/code/API_definitions/geofencing-subscriptions.yaml b/code/API_definitions/geofencing-subscriptions.yaml
index 0d05a7ce..462ff0d0 100644
--- a/code/API_definitions/geofencing-subscriptions.yaml
+++ b/code/API_definitions/geofencing-subscriptions.yaml
@@ -36,7 +36,7 @@ info:
 
     It is mandatory in the subscription to provide the event `type` for which the client would like to subscribe.
 
-    Following event ``type`` are managed for this API:
+    Following event ``types`` are managed for this API:
       - ``org.camaraproject.geofencing-subscriptions.v0.area-entered``  - Event triggered when the device enters the given area
 
       - ``org.camaraproject.geofencing-subscriptions.v0.area-left``     - Event triggered when the device leaves the given area