Restructure artifacts directory for $ref consumption and bundling

[hdamker]

Problem description

The artifacts/ directory currently contains template files (CAMARA_common.yaml, notification-as-cloud-event.yaml, event-subscription-template.yaml) in a flat layout. These templates duplicate schemas (ErrorInfo, XCorrelator, CloudEvent, Source, DateTime are defined identically in multiple files) and are structured as standalone APIs rather than as $ref-consumable components.

With the move toward $ref-based consumption of common schemas (#577) and the bundling model proposed in ReleaseManagement#436, API repositories will adopt a canonical layout:

code/
  API_definitions/   # API source files
  common/            # Cached copy of Commonalities common schemas

The $ref paths in API source files (e.g., ../common/CAMARA_common.yaml#/components/schemas/ErrorInfo) are relative to this layout. Currently, the Commonalities templates do not use this layout, so their $ref paths differ from what API repos actually use. Templates also duplicate schemas instead of referencing a single authoritative source.

Possible evolution

Restructure artifacts/ so that relative $ref paths in templates are identical to those in API repositories:

artifacts/
├── common/                                # Authoritative common schema files
│   ├── CAMARA_common.yaml
│   └── CAMARA_event_common.yaml           # Event-specific schemas (CloudEvent, Source, DateTime)
├── api-templates/                         # Copy-and-adapt API templates (maps to API_definitions)
│   ├── sample-service.yaml                # Request-response pattern
│   ├── sample-implicit-events.yaml        # Implicit subscription (callbacks inline)
│   └── sample-service-subscriptions.yaml  # Explicit subscription management
├── event-templates/                       # Event-type specific templates (maps to Event_definitions)
│   └── sample-event-type.yaml             # Can be added later, for #600 work
└── notification-templates/                # Copy-and-adapt notification callback template
    └── sample-notification.yaml

A $ref like ../common/CAMARA_common.yaml#/components/schemas/ErrorInfo works identically in templates and in API repositories — templates serve as living proof that the structure works.

This achieves:

• Identical $ref paths: Templates use the same relative paths as API repositories. No path adjustment needed when copying a template.
• No schema duplication: Templates reference common/ instead of embedding their own copies of ErrorInfo, XCorrelator, CloudEvent, etc.
• Separation of common schemas and templates: common/ contains only $ref-consumable component files. Templates show how to use them for each API pattern.
• Event schema separation: CAMARA_event_common.yaml contains event-specific schemas (CloudEvent, Source, DateTime) separate from general data types. Request-response APIs only need CAMARA_common.yaml.
• Directory mapping: api-templates/ maps to API_definitions, event-templates/ maps to Event_definitions — clear correspondence between template directories and API repo directories.
• Three API patterns covered: request-response, implicit subscription, and explicit subscription — each with a dedicated template.

The event-templates/ directory can be added later as part of #600 resolution. The existing flat files (notification-as-cloud-event.yaml, event-subscription-template.yaml) would be superseded by the new structure.

Alternative solution

Keep the flat layout and add CAMARA_event_common.yaml alongside the existing files. This avoids the restructuring effort but leaves schema duplication in place and means template $ref paths don't match API repo paths.

Additional context

Related issues and PRs:

• Establish guidance for consuming schemas from CAMARA_common.yaml #577 — Commonalities consumption discussion (proposed common/ + template layout)
• Refactor event definition in Event Subscription Template #600 — Event definition refactoring (decoupling CloudEvent as reusable base)
• Improve CloudEvents Compliance and Consolidate Subscription API Design Across CAMARA Subprojects #556 — CloudEvents compliance and subscription API consolidation
• docs: add Commonalities consumption and bundling design ReleaseManagement#436 — Bundling design document
• Implement CAMARA Validation Framework v1 ReleaseManagement#448 — Validation framework v1 umbrella

Directory structure discussed and refined in hdamker#1 with input from @rartych.

[tanjadegroot]

There was a cloudevent notification receiver side template as well (notification-as-cloud-event.yaml). Is it dropper ?
I think it is still useful, but it should be more clearly called "sample-cloudevent-notification-receiver.yaml" or something.

Also it is not clear what is the difference between event-templates and notification templates ?

For me, a notification is a possible consequence of an event that happened. And the term "cloudevent" actually refers to a notification format IMHO.

If the intent is to distinguish between notification sender and receiver, then it would be clearer to include those sender and receiver notions in the names of the folders and the sample files.

[hdamker]

There was a cloudevent notification receiver side template as well (notification-as-cloud-event.yaml). Is it dropper ? I think it is still useful, but it should be more clearly called "sample-cloudevent-notification-receiver.yaml" or something.

The file sample-notification.yaml is meant to be it. Get the point about a clear name, but do you have a proposal which is so shorter than "sample-cloudevent-notification-receiver.yaml" (which is also not fully clear from my perspective).

Also it is not clear what is the difference between event-templates and notification templates ?

event-templates are meant to be only the event types and their structure. Neither sender nor receiver side, the content.

For me, a notification is a possible consequence of an event that happened. And the term "cloudevent" actually refers to a notification format IMHO.

Exactly the "notification format" is meant in event-templates.

If the intent is to distinguish between notification sender and receiver, then it would be clearer to include those sender and receiver notions in the names of the folders and the sample files.

Proposals for clearer names are welcome, see above.