fix: align common files and templates with Commonalities #606

code/API_definitions/sample-service-subscriptions.yaml

@@ -13,7 +13,7 @@
     name: Apache 2.0
     url: https://www.apache.org/licenses/LICENSE-2.0.html
   version: wip
-  x-camara-commonalities: 0.8.0
+  x-camara-commonalities: 0.7.0
 
 externalDocs:
   description: Product documentation at CAMARA
@@ -220,12 +220,7 @@
     openId:
       $ref: "../common/CAMARA_common.yaml#/components/securitySchemes/openId"
     notificationsBearerAuth:
-      type: http
-      scheme: bearer
-      bearerFormat: "{$request.body#/sinkCredential.credentialType}"
-      description: |
-        Bearer token for notification delivery. Token format is determined
-        by `sinkCredential.credentialType` in the subscription request.
+      $ref: "../common/CAMARA_event_common.yaml#/components/securitySchemes/notificationsBearerAuth"
 
   parameters:
     SubscriptionId:
@@ -310,8 +305,6 @@
           pattern: ^https:\/\/.+$
           description: The address to which events shall be delivered using the selected protocol.
           example: "https://endpoint.example.com/sink"
-        sinkCredential:
-          $ref: "../common/CAMARA_event_common.yaml#/components/schemas/SinkCredential"
         types:
           description: |
             Camara Event types eligible to be delivered by this subscription.
@@ -376,8 +369,8 @@
         globally unique, so two different API groups can independently define
         identically-named event types without any collision risk.
       enum:
-        - org.camaraproject.api-name.v0.event-type1
-        - org.camaraproject.api-name.v0.event-type2
+        - org.camaraproject.sample-service-subscriptions.v0.event-type1
+        - org.camaraproject.sample-service-subscriptions.v0.event-type2
 
     # ─────────────────────────────────────────────────────────────────────────
     # Subscription lifecycle event group (Commonalities-owned structure,
@@ -406,9 +399,9 @@
       discriminator:
         propertyName: type
         mapping:
-          org.camaraproject.api-name.v0.subscription-started: "#/components/schemas/EventSubscriptionStarted"
-          org.camaraproject.api-name.v0.subscription-updated: "#/components/schemas/EventSubscriptionUpdated"
-          org.camaraproject.api-name.v0.subscription-ended: "#/components/schemas/EventSubscriptionEnded"
+          org.camaraproject.sample-service-subscriptions.v0.subscription-started: "#/components/schemas/EventSubscriptionStarted"
+          org.camaraproject.sample-service-subscriptions.v0.subscription-updated: "#/components/schemas/EventSubscriptionUpdated"
+          org.camaraproject.sample-service-subscriptions.v0.subscription-ended: "#/components/schemas/EventSubscriptionEnded"
 
     SubscriptionLifecycleEventType:
       type: string
@@ -419,9 +412,9 @@
         Kept as a separate named schema so the set of valid lifecycle type
         strings can be referenced independently from the discriminated schema.
       enum:
-        - org.camaraproject.api-name.v0.subscription-started
-        - org.camaraproject.api-name.v0.subscription-updated
-        - org.camaraproject.api-name.v0.subscription-ended
+        - org.camaraproject.sample-service-subscriptions.v0.subscription-started
+        - org.camaraproject.sample-service-subscriptions.v0.subscription-updated
+        - org.camaraproject.sample-service-subscriptions.v0.subscription-ended
 
     # ─────────────────────────────────────────────────────────────────────────
     # API-specific notification event group
@@ -449,8 +442,8 @@
       discriminator:
         propertyName: "type"
         mapping:
-          org.camaraproject.api-name.v0.event-type1: "#/components/schemas/EventApiSpecific1"
-          org.camaraproject.api-name.v0.event-type2: "#/components/schemas/EventApiSpecific2"
+          org.camaraproject.sample-service-subscriptions.v0.event-type1: "#/components/schemas/EventApiSpecific1"
+          org.camaraproject.sample-service-subscriptions.v0.event-type2: "#/components/schemas/EventApiSpecific2"
 
     # ─────────────────────────────────────────────────────────────────────────
     # Callback union (API project-owned)
@@ -478,7 +471,7 @@
     # Concrete event schemas — API-specific (API project-owned)
     # ─────────────────────────────────────────────────────────────────────────
 
     EventApiSpecific1:
       description: event structure for event-type event 1
       allOf:
         - $ref: "#/components/schemas/ApiNotificationEvent"
@@ -490,7 +483,7 @@
                 Event-specific payload for event-type1.
                 Replace with the actual data schema for this event type.
 
     EventApiSpecific2:
       description: event structure for event-type event 2
       allOf:
         - $ref: "#/components/schemas/ApiNotificationEvent"
@@ -507,7 +500,7 @@
     # Data payloads are referenced from CAMARA_event_common.yaml.
     # ─────────────────────────────────────────────────────────────────────────
 
     EventSubscriptionStarted:
       description: event structure for event subscription started
       allOf:
         - $ref: "#/components/schemas/SubscriptionLifecycleEvent"
@@ -516,7 +509,7 @@
             data:
               $ref: "../common/CAMARA_event_common.yaml#/components/schemas/SubscriptionStarted"
 
     EventSubscriptionUpdated:
       description: event structure for event subscription updated
       allOf:
         - $ref: "#/components/schemas/SubscriptionLifecycleEvent"
@@ -525,7 +518,7 @@
             data:
               $ref: "../common/CAMARA_event_common.yaml#/components/schemas/SubscriptionUpdated"
 
     EventSubscriptionEnded:
       description: event structure for event subscription ended
       allOf:
         - $ref: "#/components/schemas/SubscriptionLifecycleEvent"
@@ -597,7 +590,7 @@
     #           $ref: "../common/CAMARA_event_common.yaml#/components/schemas/NATSSettings"
     # ─────────────────────────────────────────────────────────────────────────
 
     HTTPSubscriptionRequest:
       description: Subscription request for HTTP-based event delivery.
       allOf:
         - $ref: "#/components/schemas/SubscriptionRequest"
@@ -606,7 +599,7 @@
             protocolSettings:
               $ref: "../common/CAMARA_event_common.yaml#/components/schemas/HTTPSettings"
 
     HTTPSubscriptionResponse:
       description: Subscription resource returned for HTTP-based event delivery.
       allOf:
         - $ref: "#/components/schemas/Subscription"

code/API_definitions/sample-service.yaml

@@ -96,6 +96,8 @@
                 maxItems: 1000
                 items:
                   $ref: "#/components/schemas/Resource"
+        "400":
+          $ref: "../common/CAMARA_common.yaml#/components/responses/Generic400"
         "401":
           $ref: "../common/CAMARA_common.yaml#/components/responses/Generic401"
         "403":
@@ -122,6 +124,8 @@
             application/json:
               schema:
                 $ref: "#/components/schemas/Resource"
+        "400":
+          $ref: "../common/CAMARA_common.yaml#/components/responses/Generic400"
         "401":
           $ref: "../common/CAMARA_common.yaml#/components/responses/Generic401"
         "403":
@@ -146,6 +150,8 @@
           headers:
             x-correlator:
               $ref: "../common/CAMARA_common.yaml#/components/headers/x-correlator"
+        "400":
+          $ref: "../common/CAMARA_common.yaml#/components/responses/Generic400"
         "401":
           $ref: "../common/CAMARA_common.yaml#/components/responses/Generic401"
         "403":
@@ -215,7 +221,7 @@
       required:
         - name
       properties:
         name:
           type: string
           maxLength: 128
           description: Human-readable name for the resource
@@ -230,7 +236,7 @@
       properties:
         resourceId:
           $ref: "#/components/schemas/ResourceId"
         name:
           type: string
           maxLength: 128
           description: Human-readable name for the resource

code/common/CAMARA_common.yaml

@@ -47,18 +47,12 @@
       example: "2018-04-05T17:31:00Z"
     TimePeriod:
       type: object
-      description: A period of time defined by a start date and an optional end date
+      description: A period of time defined by a start date and an optional end date. If endDate is not included, then the period has no ending date.
       properties:
         startDate:
-          type: string
-          format: date-time
-          maxLength: 64
-          description: An instant of time, starting of the TimePeriod. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone.
+          $ref: "#/components/schemas/DateTime"
         endDate:
-          type: string
-          format: date-time
-          maxLength: 64
-          description: An instant of time, ending of the TimePeriod. If not included, then the period has no ending date. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone.
+          $ref: "#/components/schemas/DateTime"
       required:
         - startDate
     ErrorInfo:
@@ -75,11 +69,11 @@
           minimum: 100
           maximum: 599
           description: HTTP response status code
         code:
           type: string
           maxLength: 96
           description: A human-readable code to describe the error
         message:
           type: string
           maxLength: 512
           description: A human-readable description of what the event represents

code/common/CAMARA_event_common.yaml

@@ -14,6 +14,15 @@
   x-camara-commonalities: 0.7.0
 
 components:
+  securitySchemes:
+    notificationsBearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: "{$request.body#/sinkCredential.credentialType}"
+      description: |
+        Bearer token for notification delivery. Token format is determined
+        by `sinkCredential.credentialType` in the subscription request.
+
   schemas:
 
     # ─────────────────────────────────────────────────────────────────────────
@@ -38,13 +47,13 @@
         - 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: |
@@ -92,7 +101,7 @@
     # across all CAMARA APIs that support explicit subscriptions.
     # ─────────────────────────────────────────────────────────────────────────
 
     SubscriptionId:
       type: string
       maxLength: 256
       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.
@@ -158,13 +167,13 @@
       type: object
       description: HTTP protocol settings for event delivery.
       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. 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
             maxLength: 512
         method:
@@ -263,38 +272,38 @@
         credentialType:
           type: string
           enum:
-            - PLAIN
+            # - PLAIN  # not used in CAMARA
             - ACCESSTOKEN
             - PRIVATE_KEY_JWT
           description: |
             The type of the credential - MUST be set to ACCESSTOKEN or PRIVATE_KEY_JWT for now
       discriminator:
         propertyName: credentialType
         mapping:
-          PLAIN: "#/components/schemas/PlainCredential"
+          # PLAIN: "#/components/schemas/PlainCredential"  # not used in CAMARA
           ACCESSTOKEN: "#/components/schemas/AccessTokenCredential"
           PRIVATE_KEY_JWT: "#/components/schemas/PrivateKeyJWTCredential"
       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
-              maxLength: 256
-            secret:
-              description: The secret might be a password or passphrase.
-              type: string
-              maxLength: 512
+    # PlainCredential:  # not used in CAMARA
+    #   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
+    #           maxLength: 256
+    #         secret:
+    #           description: The secret might be a password or passphrase.
+    #           type: string
+    #           maxLength: 512
 
     AccessTokenCredential:
       type: object
@@ -353,7 +362,7 @@
           $ref: "#/components/schemas/InitiationReason"
         subscriptionId:
           $ref: "#/components/schemas/SubscriptionId"
         initiationDescription:
           type: string
           maxLength: 512
           description: Description of subscription initiation
@@ -376,7 +385,7 @@
           $ref: "#/components/schemas/UpdateReason"
         subscriptionId:
           $ref: "#/components/schemas/SubscriptionId"
         updateDescription:
           type: string
           maxLength: 512
           description: Description of subscription update
@@ -401,7 +410,7 @@
           $ref: "#/components/schemas/TerminationReason"
         subscriptionId:
           $ref: "#/components/schemas/SubscriptionId"
         terminationDescription:
           type: string
           maxLength: 512
           description: Description of subscription termination