fix: restructure artifacts directory for $ref consumption

README.md

@@ -7,26 +7,33 @@
 <img src="https://img.shields.io/badge/Working%20Group-red">
 
 # Commonalities
-Repository to describe and document common guidelines and assets for CAMARA APIs
+Repository to describe and document common guidelines and artifacts for CAMARA APIs
 
 ## Scope
-* Guidelines and assets for “Commonalities” (see APIBacklog.md)  
+* Guidelines and artifacts for “Commonalities” (see APIBacklog.md)  
 * All deliverables are mandatory for all CAMARA Sub Projects 
 * Describe, develop, document and test the deliverables
 * Started: October 2021
 
 ## Documents for CAMARA Sub Projects
 
-The documents that are relevant for CAMARA API Repositories are found in the `documentation` directory (at the top-level). The rest of the sub-directories are primarily for internal working of the Commonalities Working Group.
+The documents that are relevant for CAMARA API Sub Projects are found in the `documentation` directory (at the top-level).
 
 The `artifacts` directory contains:
 * templates for creating Github issues
-* common data and error formats for CAMARA APIs in [CAMARA_common.yaml](artifacts/CAMARA_common.yaml)
-* notification subscription template: [event-subscription-template.yaml](artifacts/camara-cloudevents/event-subscription-template.yaml)
-* OAS definition of CAMARA Event using CloudEvents: [notification-as-cloud-event.yaml](artifacts/notification-as-cloud-event.yaml)
-* Common artifacts for testing error scenarios for device and phoneNumber: in [artifacts/testing](artifacts/testing) folder 
+* common data types and error formats for CAMARA APIs in [artifacts/common](artifacts/common):
+  * [CAMARA_common.yaml](artifacts/common/CAMARA_common.yaml) — shared schemas, error responses, headers, and parameters
+  * [CAMARA_event_common.yaml](artifacts/common/CAMARA_event_common.yaml) — CloudEvents envelope, subscription management, protocol settings, credentials, and subscription-specific error responses
+* API templates demonstrating `$ref` consumption of common schemas in [artifacts/api-templates](artifacts/api-templates):
+  * [sample-service.yaml](artifacts/api-templates/sample-service.yaml) — request-response CRUD template
+  * [sample-service-subscriptions.yaml](artifacts/api-templates/sample-service-subscriptions.yaml) — explicit subscription management template
+* notification callback template in [artifacts/notification-templates](artifacts/notification-templates):
+  * [sample-notification.yaml](artifacts/notification-templates/sample-notification.yaml) — receiver-side notification endpoint
+* common test scenarios in [artifacts/testing](artifacts/testing) — error handling for device/phoneNumber APIs and subscription APIs
 
-### Frequently-accessed output documents
+The remaining sub-directories are primarily for internal working of the Commonalities Working Group.
+
+### Links to frequently-accessed documents
 
 A list of some of the frequently accessed documents that are an output of the work done in the Commonalities Working Group is provided below. Note that the links are relative to the branch selected. Refer to the section below for released versions. 
 

artifacts/api-templates/sample-service.yaml

@@ -0,0 +1,245 @@
+openapi: 3.0.3
+info:
+  title: Sample Service
+  description: |
+    Template for a request-response CAMARA API.
+
+    Copy this file to your API repository's `code/API_definitions/` directory
+    and adapt it to your API's resources and operations.
+
+    This template demonstrates:
+    - `$ref` to `../common/CAMARA_common.yaml` for shared schemas, error responses,
+      parameters, headers, and security schemes
+    - Two options for error responses:
+      - Option A: Pure `$ref` for responses using only generic error codes
+      - Option B: Local response definition extending generic errors with API-specific codes
+  license:
+    name: Apache 2.0
+    url: https://www.apache.org/licenses/LICENSE-2.0.html
+  version: wip
+  x-camara-commonalities: 0.7.0
+externalDocs:
+  description: Product documentation at CAMARA
+  url: https://github.com/camaraproject/{apiRepository}
+  # {apiRepository} MUST be replaced by the CAMARA API Repository name where the API specification is hosted.
+servers:
+  - url: "{apiRoot}/sample-service/vwip"
+    variables:
+      apiRoot:
+        default: http://localhost:9091
+        description: API root, defined by the service provider, e.g. `api.example.com` or `api.example.com/somepath`
+tags:
+  - name: Resources
+    description: Operations on sample resources
+security:
+  - openId:
+      - sample-service:resource:read
+      - sample-service:resource:write
+paths:
+  /resources:
+    post:
+      tags:
+        - Resources
+      summary: Create a resource
+      description: Creates a new resource with the provided properties.
+      operationId: createResource
+      parameters:
+        - $ref: "../common/CAMARA_common.yaml#/components/parameters/x-correlator"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CreateResource"
+      responses:
+        "201":
+          description: Resource created
+          headers:
+            x-correlator:
+              $ref: "../common/CAMARA_common.yaml#/components/headers/x-correlator"
+          content:
+            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":
+          $ref: "../common/CAMARA_common.yaml#/components/responses/Generic403"
+        "409":
+          $ref: "../common/CAMARA_common.yaml#/components/responses/Generic409"
+        "422":
+          $ref: "../common/CAMARA_common.yaml#/components/responses/Generic422"
+        "429":
+          $ref: "../common/CAMARA_common.yaml#/components/responses/Generic429"
+        "500":
+          $ref: "../common/CAMARA_common.yaml#/components/responses/Generic500"
+    get:
+      tags:
+        - Resources
+      summary: List resources
+      description: Returns a list of all resources accessible to the API consumer.
+      operationId: listResources
+      parameters:
+        - $ref: "../common/CAMARA_common.yaml#/components/parameters/x-correlator"
+      responses:
+        "200":
+          description: List of resources
+          headers:
+            x-correlator:
+              $ref: "../common/CAMARA_common.yaml#/components/headers/x-correlator"
+          content:
+            application/json:
+              schema:
+                type: array
+                minItems: 0
+                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":
+          $ref: "../common/CAMARA_common.yaml#/components/responses/Generic403"
+        "500":
+          $ref: "../common/CAMARA_common.yaml#/components/responses/Generic500"
+  /resources/{resourceId}:
+    get:
+      tags:
+        - Resources
+      summary: Get a resource by ID
+      description: Returns the details of a specific resource identified by its ID.
+      operationId: getResource
+      parameters:
+        - $ref: "#/components/parameters/ResourceId"
+        - $ref: "../common/CAMARA_common.yaml#/components/parameters/x-correlator"
+      responses:
+        "200":
+          description: Resource details
+          headers:
+            x-correlator:
+              $ref: "../common/CAMARA_common.yaml#/components/headers/x-correlator"
+          content:
+            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":
+          $ref: "../common/CAMARA_common.yaml#/components/responses/Generic403"
+        # Option A — pure $ref for responses using only generic error codes
+        "404":
+          $ref: "../common/CAMARA_common.yaml#/components/responses/Generic404"
+        "500":
+          $ref: "../common/CAMARA_common.yaml#/components/responses/Generic500"
+    delete:
+      tags:
+        - Resources
+      summary: Delete a resource
+      description: Deletes a specific resource identified by its ID.
+      operationId: deleteResource
+      parameters:
+        - $ref: "#/components/parameters/ResourceId"
+        - $ref: "../common/CAMARA_common.yaml#/components/parameters/x-correlator"
+      responses:
+        "204":
+          description: Resource deleted
+          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":
+          $ref: "../common/CAMARA_common.yaml#/components/responses/Generic403"
+        # Option B — local response extending generic errors with API-specific codes
+        "404":
+          $ref: "#/components/responses/ResourceNotFound404"
+        "500":
+          $ref: "../common/CAMARA_common.yaml#/components/responses/Generic500"
+components:
+  securitySchemes:
+    openId:
+      $ref: "../common/CAMARA_common.yaml#/components/securitySchemes/openId"
+  responses:
+    # Option B example: API-specific error response extending generic error codes.
+    # Use this pattern when an operation needs API-specific error codes in addition
+    # to the generic ones defined in CAMARA_common.yaml.
+    ResourceNotFound404:
+      description: Resource not found
+      headers:
+        x-correlator:
+          $ref: "../common/CAMARA_common.yaml#/components/headers/x-correlator"
+      content:
+        application/json:
+          schema:
+            allOf:
+              - $ref: "../common/CAMARA_common.yaml#/components/schemas/ErrorInfo"
+              - type: object
+                properties:
+                  status:
+                    enum:
+                      - 404
+                  code:
+                    enum:
+                      - NOT_FOUND
+                      - IDENTIFIER_NOT_FOUND
+          examples:
+            GENERIC_404_NOT_FOUND:
+              description: The specified resource was not found
+              value:
+                status: 404
+                code: NOT_FOUND
+                message: The specified resource is not found.
+            RESOURCE_404_IDENTIFIER_NOT_FOUND:
+              description: API-specific — some identifier cannot be matched to a resource
+              value:
+                status: 404
+                code: IDENTIFIER_NOT_FOUND
+                message: Some of the provided identifiers are not found.
+  parameters:
+    ResourceId:
+      name: resourceId
+      in: path
+      required: true
+      description: Identifier of the resource to operate on
+      schema:
+        $ref: "#/components/schemas/ResourceId"
+  schemas:
+    ResourceId:
+      type: string
+      format: uuid
+      maxLength: 36
+      description: Unique identifier for the resource
+    CreateResource:
+      description: Properties for creating a new resource
+      type: object
+      required:
+        - name
+      properties:
+        name:
+          type: string
+          maxLength: 128
+          description: Human-readable name for the resource
+        device:
+          $ref: "../common/CAMARA_common.yaml#/components/schemas/Device"
+    Resource:
+      description: A resource managed by the API
+      type: object
+      required:
+        - resourceId
+        - name
+      properties:
+        resourceId:
+          $ref: "#/components/schemas/ResourceId"
+        name:
+          type: string
+          maxLength: 128
+          description: Human-readable name for the resource
+        device:
+          $ref: "../common/CAMARA_common.yaml#/components/schemas/Device"