Support Commonalities consumption and bundling workflow across CAMARA repositories

[hdamker]

Problem description

CAMARA currently lacks a standardized, tooling-supported way for API repositories to consume shared schemas from CAMARA_common.yaml and similar shared artifacts without copy-paste. This creates avoidable maintenance overhead, weak provenance, and inconsistent repository structures and review practices.

The need has become more urgent due to recent Commonalities schema updates, including OWASP-related changes, which should be consumable by API repositories without each repository solving the same problem independently.

The design discussion in Commonalities issue #577 converged on a controlled local copy model with release-plan-driven dependency traceability, CI-managed synchronization, and release-time bundling.

A design proposal has been prepared for ReleaseManagement and will be linked through a dedicated PR. It is intended to support discussion across Release Management, Commonalities, tooling, and pilot API repositories.

This issue is intended to act as the umbrella for agreeing the implementation direction and coordinating follow-up issues across repositories.

Possible evolution

Adopt and implement the following model:

• API repositories consume Commonalities schemas through a controlled local copy in code/common/
• release-plan.yaml.dependencies.commonalities_release is the authoritative source of the intended Commonalities dependency
• the local Commonalities file is treated as cache and synchronized by automation
• source API definitions on main use relative $ref and bundled artifacts are not committed on main
• PR workflows provide bundled artifacts and bundled diffs for reviewer visibility
• snapshot creation applies the stricter release-readiness validation and bundles standalone release artifacts on snapshot/release branches

Expected implementation work includes:

• Commonalities follow-up to make CAMARA_common.yaml directly consumable
• tooling support for synchronization, validation, and bundling
• pilot adoption in selected API repositories
• later consolidation in a broader validation framework v1

Alternative solution

Alternative approaches have been discussed, including URL-based references, submodules, package-based distribution, and committing bundled artifacts on main.

The current recommendation is to avoid those in favor of:

• controlled local copies for source-time tooling compatibility and offline development
• generated bundled artifacts for PR review visibility
• bundled standalone files only on snapshot/release branches and tags

A fallback alternative would be to support compatibility validation around placeholder-filled shared schemas, but this is considered less desirable than evolving Commonalities toward directly consumable shared content.

Additional context

Related discussion and inputs:

• Commonalities issue #577: Establish guidance for consuming schemas from CAMARA_common.yaml Commonalities#577
• Commonalities issue #556: Improve CloudEvents Compliance and Consolidate Subscription API Design Across CAMARA Subprojects Commonalities#556
• Commonalities PR #541: Clarification meaning of {{API_NAME}}.{{SPECIFIC_CODE}} Commonalities#541
• Commonalities PR #517: ErrorInfo Schema properties alignment Commonalities#517

Suggested follow-up from this umbrella issue:

• ReleaseManagement review of the design document PR
• tooling issue(s) for synchronization, validation, and bundling support
• Commonalities issue(s) for consumable shared schema structure and placeholder removal where needed
• pilot implementation issues in selected API repositories