docs: add Commonalities consumption and bundling design

[hdamker]

What type of PR is this?

• documentation

What this PR does / why we need it:

This PR adds a supporting design document for the Commonalities consumption and bundling model discussed in Commonalities issue #577.

The document captures the agreed direction to:

• consume CAMARA_common.yaml through a controlled local copy on main
• use release-plan.yaml.dependencies.commonalities_release as the authoritative dependency declaration
• treat the local Commonalities file as automation-managed cache
• keep bundled API definitions off main, while still providing bundled review artifacts in PRs
• apply stricter validation and bundling during snapshot creation

The document is intended to support cross-project review in Release Management, Commonalities, tooling, and pilot API repositories before implementation issues are split out.

Which issue(s) this PR references:

Related to #435

Special notes for reviewers:

This is a design/supporting document PR.

Implementation is expected to follow through linked issues in ReleaseManagement, tooling, Commonalities, and pilot API repositories after agreement on the design direction.

Changelog input

Additional documentation

This PR adds the following documentation:

- documentation/SupportingDocuments/Commonalities-Consumption-and-Bundling-Design.md

[hdamker]

Updated section 8 (Commonalities Content Expectations) to refine the placeholder handling approach. Thanks and credits to @rartych for the idea and testing it in a PoC

Key change: Section 8 is now split into two independent concerns:

8.1 Placeholder Removal — Instead of deleting placeholder patterns ({{SPECIFIC_CODE}}, {{field}}), the recommended approach is to comment them out. This makes CAMARA_common.yaml immediately consumable via $ref — YAML parsers, bundling tools, and Spectral ignore comments, so the file becomes valid OpenAPI content. The commented placeholders remain as human-readable documentation showing where APIs add their own content. The change is minimal (~30 lines).

8.2 API-Specific Error Code Extension — How APIs add their own error codes (allOf, property override, own response composition) is explicitly separated as an independent topic. It does not need to be resolved before CAMARA_common.yaml becomes consumable. This can be worked out incrementally as APIs adopt the $ref model.

Why this matters: The previous version coupled placeholder removal with the allOf extension pattern, making both a prerequisite for bundling. Separating them means the Commonalities side can make a minimal change (commenting ~30 lines) to unblock $ref consumption, without first solving the broader question of how APIs extend Generic error responses.

[hdamker]

Added in-place replacement as an explicit design principle (executive summary point 5, design goals, sections 5 and 9.1):

The API source file and the bundled file occupy the same path (code/API_definitions/api-name.yaml) — on main the file may contain external $ref to common/ or modules/; on snapshot/release branches these are replaced with the referenced content.

[tanjadegroot]

For me it looks great, just one thought for consideration if useful.

/LGTM

[hdamker]

Comments addressed, approved and no new comments since a week.