Refactor configuration schema in CAMARA_event_common.yaml

artifacts/api-templates/sample-service-subscriptions.yaml

@@ -314,7 +314,7 @@ components:
           items:
             $ref: "#/components/schemas/ApiEventType"
         config:
-          $ref: "../common/CAMARA_event_common.yaml#/components/schemas/Config"
+          $ref: "#/components/schemas/Config"
       discriminator:
         propertyName: protocol
         mapping:
@@ -354,7 +354,7 @@ components:
           items:
             $ref: "#/components/schemas/ApiEventType"
         config:
-          $ref: "../common/CAMARA_event_common.yaml#/components/schemas/Config"
+          $ref: "#/components/schemas/Config"
         id:
           $ref: "../common/CAMARA_event_common.yaml#/components/schemas/SubscriptionId"
         startsAt:
@@ -413,6 +413,47 @@ components:
         pagination:
           $ref: "../common/CAMARA_common.yaml#/components/schemas/Pagination"
 
+    # ─────────────────────────────────────────────────────────────────────────
+    # Config (API-specific due to subscriptionDetail)
+    #
+    # Extends the Commonalities-owned ConfigBase via allOf, adding the required
+    # `subscriptionDetail` property typed against this API's own
+    # CreateSubscriptionDetail schema. `subscriptionDetail` cannot be defined
+    # in CAMARA_event_common.yaml because it is API-specific.
+    # This is also where each API project add the predefined, optional `initialEvent` property.
+    # ─────────────────────────────────────────────────────────────────────────
+
+    Config:
+      description: |
+        Implementation-specific configuration parameters needed by the subscription manager
+        for acquiring events. Extends `ConfigBase` from `CAMARA_event_common.yaml` with the
+        required, API-specific `subscriptionDetail` property. As an example, this template
+        also includes the predefined, optional `initialEvent` property; API projects MAY
+        omit it if sending a notification when a subscription is created is not relevant to the
+        API’s event type(s).
+        Note: if a request is performed for several event types, all subscribed events will
+        use the same `config` parameters.
+      allOf:
+        - $ref: "../common/CAMARA_event_common.yaml#/components/schemas/ConfigBase"
+        - type: object
+          required:
+            - subscriptionDetail
+          properties:
+            subscriptionDetail:
+              $ref: "#/components/schemas/CreateSubscriptionDetail"
+            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.
+                It is up to the API project team to decide whether to keep it and to provide an explanation in the description.
+
+    CreateSubscriptionDetail:
+      description: |
+        The detail of the requested event subscription.
+        Replace with the actual API-specific subscription detail properties
+        (e.g. `device`, `area`) for this API project.
+      type: object
+
     # ─────────────────────────────────────────────────────────────────────────
     # API-specific event type enum (contains sample-service placeholders)
     # ─────────────────────────────────────────────────────────────────────────

artifacts/common/CAMARA_event_common.yaml

@@ -49,19 +49,19 @@
         - type
         - time
       properties:
         id:
           type: string
           maxLength: 256
           description: Identifier of this event, unique within the source context.
         source:
           $ref: "#/components/schemas/Source"
         type:
           type: string
           maxLength: 512
           description: |
             Identifies the event type. CAMARA APIs use reverse-DNS notation:
             `org.camaraproject.<api-name>.<event-version>.<event-name>`
             The api-name segment makes each type globally unique across API groups.
         specversion:
           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)
@@ -101,6 +101,11 @@
     # Configuration and identification schemas used by the subscription
     # management endpoints. These are Commonalities-owned and identical
     # across all CAMARA APIs that support explicit subscriptions.
+    #
+    # ConfigBase is not a complete `Config` schema: it only holds the
+    # attributes common to every API project. Each API project MUST define
+    # its own `Config` schema locally (extending ConfigBase via `allOf`) to
+    # add the required, API-specific `subscriptionDetail` property.
     # ─────────────────────────────────────────────────────────────────────────
 
     SubscriptionId:
@@ -109,41 +114,31 @@
       description: The unique identifier of the subscription in the scope of the subscription manager. When this information is contained within an event notification, it SHALL be referred to as `subscriptionId` as per the Commonalities Event Notification Model.
       example: qs15-h556-rt89-1298
 
-    Config:
+    ConfigBase:
       description: |
-        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 types, all subscribed events will use same `config` parameters.
+        Base schema for the `config` object: implementation-specific configuration parameters
+        needed by the subscription manager for acquiring events. It defines the attributes
+        common to all CAMARA subscription APIs (`subscriptionExpireTime`, `subscriptionMaxEvents`).
+
+        API projects MUST define their own `Config` schema in their main OpenAPI file, extending
+        `ConfigBase` via `allOf` to add the required, API-specific `subscriptionDetail` property.
+        API projects MAY also add the predefined, optional `initialEvent` property (see sample-service-subscriptions.yaml),
+        or omit it if sending a notification at subscription creation time is not relevant to the API’s event type(s).
       type: object
-      required:
-        - subscriptionDetail
       properties:
-        subscriptionDetail:
-          $ref: "#/components/schemas/CreateSubscriptionDetail"
         subscriptionExpireTime:
           type: string
           format: date-time
           maxLength: 64
           example: 2023-01-17T13:18:23.682Z
-          description: The subscription expiration time (in date-time format) requested by the API consumer. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. Up to API project decision to keep it.
+          description: The subscription expiration time (in date-time format) requested by the API consumer. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone.
         subscriptionMaxEvents:
           type: integer
           format: int32
-          description: Identifies the maximum number of event reports to be generated (>=1) requested by the API consumer - Once this number is reached, the subscription ends. Up to API project decision to keep it.
+          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
           maximum: 1000000
           example: 5
-        initialEvent:
-          type: boolean
-          description: |
-            Set to `true` by API consumer if consumer wants to get an event as soon as the subscription is created and current situation reflects event request.
-            Example: Consumer request Roaming event. If consumer sets initialEvent to true and device is in roaming situation, an event is triggered
-            Up to API project decision to keep it.
-
-    CreateSubscriptionDetail:
-      description: The detail of the requested event subscription.
-      type: object
 
     # ─────────────────────────────────────────────────────────────────────────
     # Section 3: Protocol support