Config schema in CAMARA_event_common.yaml cannot be reused via $ref across API definitions

[rartych]

Problem description

The Config schema in CAMARA_event_common.yaml is intended to be a Commonalities-owned, reusable schema referenced by API projects via $ref. This pattern is used in the Commonalities subscription template (sample-service-subscriptions.yaml, lines 315 and 358).

However, Config contains a required property subscriptionDetail resolved through an internal $ref pointing inside the same file:

Config:
  type: object
  required:
    - subscriptionDetail
  properties:
    subscriptionDetail:
      $ref: "#/components/schemas/CreateSubscriptionDetail"   # resolves within CAMARA_event_common.yaml

subscriptionDetail is inherently API-specific — it carries properties such as device, area, or event type filters that differ per API. These must be defined in the API's own main OpenAPI file, not in the common file.

Because the $ref: "#/components/schemas/CreateSubscriptionDetail" anchor is always resolved relative to CAMARA_event_common.yaml, any API referencing Config from outside that file will always resolve subscriptionDetail to the empty stub CreateSubscriptionDetail defined in the common file — regardless of any API-specific CreateSubscriptionDetail defined locally. An internal $ref cannot be overridden from an external file.

Expected behavior
Rename Config to ConfigBase in CAMARA_event_common.yaml, removing subscriptionDetail and keeping only the three common optional properties. The description documents that subscriptionDetail must be added by each API project:

ConfigBase:
  description: |
    Implementation-specific configuration parameters needed by the subscription manager for acquiring events.

    API projects MUST extend this schema (via `allOf`) to add a required `subscriptionDetail` property
    typed against their own `CreateSubscriptionDetail` definition. `subscriptionDetail` carries
    API-specific event filter parameters (e.g. `device`, `area`, event type) and cannot be defined
    in this common file.
  type: object
  properties:
    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.
    subscriptionMaxEvents:
      type: integer
      format: int32
      minimum: 1
      maximum: 1000000
      example: 5
      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.
    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.
        Up to API project decision to keep it.

The empty CreateSubscriptionDetail stub (lines 142–144) can then be removed entirely from CAMARA_event_common.yaml, since its only purpose was to satisfy the internal $ref from Config. The description in ConfigBase replaces it as normative guidance.

In the API template (sample-service-subscriptions.yaml) and in each API main file, Config is defined locally by extending ConfigBase via allOf, adding the required API-specific subscriptionDetail:

Config:
  allOf:
    - $ref: "../common/CAMARA_event_common.yaml#/components/schemas/ConfigBase"
    - type: object
      required:
        - subscriptionDetail
      properties:
        subscriptionDetail:
          $ref: "#/components/schemas/CreateSubscriptionDetail"

This way ConfigBase is a genuine Commonalities-owned reusable schema, and each API project assembles the full Config locally — keeping subscriptionDetail typed against its own API-specific CreateSubscriptionDetail definition.

The CAMARA-API-Event-Subscription-and-Notification-Guide.md should be updated to reflect this pattern.

Alternative solution

Additional context
Temporary manual solution (until ConfigBase is introduced):

Copy the full Config schema from CAMARA_event_common.yaml into the API's own main OpenAPI file and replace the $ref to the common file with a local reference:

# In the API main file — local copy of Config
Config:
  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.
  type: object
  required:
    - subscriptionDetail
  properties:
    subscriptionDetail:
      $ref: "#/components/schemas/CreateSubscriptionDetail"   # local reference, NOT to CAMARA_event_common.yaml
    subscriptionExpireTime:
      type: string
      format: date-time
      maxLength: 64
      example: 2023-01-17T13:18:23.682Z
      description: ...
    subscriptionMaxEvents:
      type: integer
      format: int32
      minimum: 1
      maximum: 1000000
      example: 5
      description: ...
    initialEvent:
      type: boolean
      description: ...

CreateSubscriptionDetail:
  description: The detail of the requested event subscription.
  type: object
  properties:
    device:
      $ref: "#/components/schemas/Device"   # API-specific properties defined here

The SubscriptionRequest and Subscription schemas in the API file then reference Config locally instead of from the common file:

config:
  $ref: "#/components/schemas/Config"   # local, NOT "../common/CAMARA_event_common.yaml#/components/schemas/Config"