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 (camaraproject#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/ to mirror the canonical API repo layout, 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                     # New: event-specific common schemas (CloudEvent, Source, DateTime)
  API_definition_templates/                      # Copy-and-adapt API templates
    sample-service.yaml                          # Request-response pattern (also base for explicit subscription APIs)
    sample-implicit-events.yaml                  # Implicit subscription pattern (callbacks inline)
    sample-service-subscriptions.yaml            # Explicit subscription management
  Notification_template/                         # 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 are 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.
• OWASP compliance from the start: New and reworked files include proper constraints (maxLength, format, min/max).
• Three API patterns covered: request-response, implicit subscription, and explicit subscription — each with a dedicated template.

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 camaraproject/Commonalities#577 — Commonalities consumption discussion (proposed common/ + template layout)
• Refactor event definition in Event Subscription Template camaraproject/Commonalities#600 — Event definition refactoring (decoupling CloudEvent as reusable base)
• Improve CloudEvents Compliance and Consolidate Subscription API Design Across CAMARA Subprojects camaraproject/Commonalities#556 — CloudEvents compliance and subscription API consolidation
• docs: add Commonalities consumption and bundling design camaraproject/ReleaseManagement#436 — Bundling design document
• Implement CAMARA Validation Framework v1 camaraproject/ReleaseManagement#448 — Validation framework v1 umbrella

Directory and file naming is open for discussion. The key design point is that the relative path structure in artifacts/ matches the canonical layout in API repositories, so that $ref paths work identically in both places.

[rartych]

On one hand I would like to keep the current link used in multiple references: https://github.com/camaraproject/Commonalities/blob/main/artifacts/CAMARA_common.yaml

On the other hand the path in $ref in templates should be identical as in API repositories.
for example:
api-name.yaml is src/
CAMARA_common.yaml is in common/
and src/ and common/ are in the code/API_definitions:

$ref: '../common/CAMARA_common.yaml#/components/parameters/x-correlator'

[hdamker]

On one hand I would like to keep the current link used in multiple references: https://github.com/camaraproject/Commonalities/blob/main/artifacts/CAMARA_common.yaml

The URL artifacts/CAMARA_common.yaml is referenced in only 7 places across 3 repos:

Repo	File	Type
Commonalities	README.md	Documentation link
Commonalities	CHANGELOG.md	Historical reference
Commonalities	documentation/CAMARA-API-Design-Guide.md	Design guide section 2.1
APIBacklog	documentation/SupportingDocuments/.../camara-notification-api-v0.1.9.yaml	Old API proposal (historical)
APIBacklog	documentation/SupportingDocuments/.../camara-capability-api-v0.4.2.yaml	Old API proposal (historical)
APIBacklog	documentation/SupportingDocuments/.../camara-runtime-restrictions-api-v0.1.6 (1).yaml	Old API proposal (historical)
NetworkAccessManagement	code/API_definitions/Domain/CAMARA_common.yaml	Local copy of the file (not a URL reference)

The notification-as-cloud-event.yaml and event-subscription-template.yaml URLs are only referenced in Commonalities' own README.md and CHANGELOG.md.

On the other hand the path in $ref in templates should be identical as in API repositories. for example: api-name.yaml is src/ CAMARA_common.yaml is in common/ and src/ and common/ are in the code/API_definitions:

$ref: '../common/CAMARA_common.yaml#/components/parameters/x-correlator'

The proposal is not to use src/ but "swap source and bundle" in place between main (source with refs, wip etc) and snapshot/release branches. The intention is the same: the refs within the templates are correct when the template YAML is copied into the API_definitions directory of an API repository.

[rartych]

The alt-right LLM wrote:
The proposal is excellent—technically sound, forward-looking, and perfectly timed.

Finally I have propmpted the following directory structure

artifacts/
├── common/                          # Authoritative common schema files
│   ├── CAMARA_common.yaml
│   └── CAMARA_event_common.yaml     # Event-specific schemas (CloudEvent, Source, DateTime, etc.)
├── api-templates/                   # Copy-and-adapt API templates
│   ├── sample-service.yaml          # Request-response pattern
│   ├── sample-implicit-events.yaml  # Implicit subscription (callbacks inline)
│   └── sample-service-subscriptions.yaml  # Explicit subscription management
├── event-templates/                 # ← NEW: Event-type specific templates
│   └── sample-event-type.yaml       # Generic reusable event type definition
└── notification-templates/          # Copy-and-adapt notification callback template
    └── sample-notification.yaml

api-templates maps to API_definitions
event-templates --> Event_definitions

The event-templates/ can be added later
But I will use it to test camaraproject#600 resolution