Establish guidance for consuming schemas from CAMARA_common.yaml

[clundie-CL]

Problem description

Section 2.1 of the CAMARA API Design Guide designates CAMARA_common.yaml as "an external repository" for common data types but provides no specification for how APIs should consume these schemas. This gap has led to inconsistent practices across CAMARA API families:

• Most APIs copy/paste schema definitions directly into their OpenAPI spec files
• Provenance is lost: No way to determine which Commonalities release tag the schemas originated from
• Version ambiguity: APIs declaring x-camara-commonalities: 0.6 could be using schemas from r3.1, r3.2, r3.3, or r3.4 (all share the same guidelines version but have different schema artifact versions)
• Maintenance burden: Schema improvements in Commonalities must be manually propagated to every API

Concrete example: In r3.4, the ErrorInfo schema properties order was fixed to align with the API Design Guide. APIs that copy/pasted ErrorInfo from earlier releases would have incorrect property ordering unless they manually tracked and re-copied the updated schema. The change was minor, but merely reflects maintenance burden required to state up to date the latest rX.Y release for a given x-camara-commonalities version.

Expected action

1. Document a standard approach in Section 2.1 of the API Design Guide for consuming schemas from CAMARA_common.yaml

2. Evaluate technical approaches for schema consumption (with community input):

   • Bundling approach (embed versioned CAMARA_common.yaml, use $ref, bundle with tools like redocly cli) - as used by Network Access Management API
   • Git submodules (pin Commonalities repo at specific tag)
   • URL-based $ref (reference GitHub raw URLs with tagged releases)
   • Package registry (publish schemas as versioned artifacts)
   • Other approaches suggested by the community

3. Add traceability guidance: Specify how APIs should indicate which Commonalities schema artifact version they're using (beyond just x-camara-commonalities guidelines version)

Evaluation criteria for approaches:

• Traceability: Can we determine which Commonalities release tag an API's schemas originated from?
• Maintainability: How easy is it to update to newer Commonalities schemas?
• Contributor Experience: Does it create barriers for new contributors?
• Tooling Compatibility: Does it work with standard OpenAPI tools (Swagger UI, Redocly, etc.)?
• CI/CD Integration: Can validation and bundling be automated?

Additional context

Related example: OptimalEdgeDiscovery API (issue #25) recently needed geographic area schemas (Area, Circle, Polygon, etc.) from CAMARA_common.yaml. Without established guidance, these were copy/pasted, creating immediate technical debt.

Versioning complexity: Between r3.1 and r3.4, x-camara-commonalities remained 0.6 while schema artifact versions evolved 0.6.1 → 0.7.1. APIs can't reliably communicate which schema versions they're using.

Related work: Issue #556 discusses bundling/dereferencing tools for CAMARA APIs, which aligns with some approaches being considered here.

Broader applicability: Establishing a bundling pattern for Commonalities consumption would also benefit:

• Large APIs: Breaking monolithic specs into templates + reusable domain-specific schemas (reducing contributor friction, minimizing merge conflicts)
• API families: Cross-repo schema sharing (e.g., EdgeCloudZone schema currently duplicated across EdgeCloud family repos, requiring manual propagation of changes)

Reference documents:

• CAMARA API Design Guide, Section 2.1
• CAMARA_common.yaml
• Network Access Management bundling example

[Kevsy]

Thanks @clundie-CL , I think this is important.

@rartych @hdamker we have discussed a similar topic in tooling, camaraproject/tooling#18 . In addition to the suggestions from @clundie-CL , can we also consider a handlebar/mustache template action, to replace placeholders in the API and Test definitions?

[hdamker]

Thanks @clundie-CL , I think this is important.

@rartych @hdamker we have discussed a similar topic in tooling, camaraproject/tooling#18 . In addition to the suggestions from @clundie-CL , can we also consider a handlebar/mustache template action, to replace placeholders in the API and Test definitions?

@clundie-CL @Kevsy

I fully agree that we need to introduce a mechanism to use common definitions from Commonalities but also across Sub Projects or within API repositories itself in an automated and reliable way. Therefore I like your evaluation approach and the criteria and would definitely support it. We just need volunteers to do it ... I'm myself currently occupied by the implementation of the the automation for our release process (as defined in https://github.com/camaraproject/ReleaseManagement/blob/main/documentation/SupportingDocuments/CAMARA-Release-Workflow-and-Metadata-Concept.md, but would be glad to see such an evaluation starting now or soon.

@Kevsy I don't think that a handlebar/mustache approach is the right approach for the demand of @clundie-CL , but I could be wrong for certain cases.

[hdamker]

@clundie-CL

Following up on my comment from two days ago: as this topic is closely related to the release automation work I am currently doing, I went ahead and made a first concrete attempt myself — with some help from AI — to structure and document a possible solution.

I’ve attached two documents:

• a shortened summary (analysis_report_issue_577_summary.md), providing a concise, decision-oriented overview, and
• a full analysis report (analysis_report_issue_577.md), for those interested in the evaluation, trade-offs, and rationale (in particular from a ReleaseManagement perspective).

The purpose is not to declare a final decision, but to make the discussion more concrete and get feedback on:

• a proposed standard approach for consuming CAMARA_common.yaml (and similar shared schemas), and
• a proposed traceability model (design-time placeholders on main, release-time resolution driven by release-plan.yaml).

Feedback from a NetworkAccessManagement perspective would be appreciated, as the needs raised in this issue were a key motivation for the proposal.

cc: @Kevsy @rartych @tanjadegroot

[Kevsy]

Thanks @hdamker - I've read and agree with the rationale behind the 'local copy' approach.

The 'controlled local copy strategy' should mention that the local repository copy of CAMARA_common.yaml is copied from Commonalities - but the details of how that is achieved, which branch/version, synching considerations etc. can be detailed later.

[clundie-CL]

Thank you for the detailed analysis, @hdamker. I'm happy to see an appetite for a solution and appears to be decent timing in view of the upcoming release automation workflows. This proposal aligns very well with the approach we've been using in NetworkAccessManagement, and I'm supportive of standardizing it across CAMARA.

NAM currently uses a bundling strategy with a local copy of CAMARA_common.yaml, which is essentially the "controlled local copy" approach you've outlined. To align with this proposal, we would need to:

1. Refactor our directory structure to follow the canonical layout:

   code/
     API_definitions/   # Move our template here
     common/            # Already have CAMARA_common.yaml
     modules/            # Move our domain schemas here

2. Adopt the release-plan.yaml + placeholder resolution pattern (Needed for Fall '26 release cycle anyway)

Local Bundling for Development Preview

One practical consideration: if bundled YAMLs are not committed to main, developers who want to preview the API in rendered form (Redocly, Swagger UI) will need to run the bundling tool locally. This is a minor workflow addition, but we may need to consider documenting in contribution guidelines.

Implementation Details

I like the idea that release automation handles validation of the "local copy" against the intents described in the release-plan.yaml. However I think there's a couple of wrinkles to iron out.

Source for Local Copy

The exact match validation implies that API's MUST copy CAMARA_common.yaml from a specific release tag (e.g., r3.4) and not main. This ensures stable, versioned schemas during development and aligns with the release-plan.yaml dependency declaration (which specifies a release tag, not main).

Recommendation: Make this clear in the guidance text that is added to guidelines.

CAMARA_common.yaml Placeholders

The main branch currently shows errors responses as follows:

    Generic400:
      description: Bad Request
      headers:
        x-correlator:
          $ref: "#/components/headers/x-correlator"
      content:
        application/json:
          schema:
            allOf:
              - $ref: "#/components/schemas/ErrorInfo"
              - type: object
                properties:
                  status:
                    enum:
                      - 400
                  code:
                    enum:
                      - INVALID_ARGUMENT
                      - OUT_OF_RANGE
                      - "{{SPECIFIC_CODE}}"
          examples:
            GENERIC_400_INVALID_ARGUMENT:
              description: Invalid Argument. Generic Syntax Exception
              value:
                status: 400
                code: INVALID_ARGUMENT
                message: Client specified an invalid argument, request body or query param.
            GENERIC_400_OUT_OF_RANGE:
              description: Out of Range. Specific Syntax Exception used when a given field has a pre-defined range or a invalid filter criteria combination is requested
              value:
                status: 400
                code: OUT_OF_RANGE
                message: Client specified an invalid range.
            GENERIC_400_{{SPECIFIC_CODE}}:
              description: Specific Syntax Exception regarding a field that is relevant in the context of the API
              value:
                status: 400
                code: "{{SPECIFIC_CODE}}"
                message: Message for specific code

I was originally going to callout issues I ran into while linting in my local environment, but noticed that PR #541 had addressed those issues.

One practical concern: CAMARA_common.yaml contains examples with placeholders (e.g., code: "{{SPECIFIC_CODE}}"). While the syntax is valid, these placeholders are meant to be replaced in API definitions. This creates a conflict:

• If an API keeps the placeholders in their local copy → propagate to the API specification
• If an API removes/replaces them → "exact match validation" fails

I would love feedback from the community on the best way to handle this. I imagine the solution is some mixture of either addressing placeholders in CAMARA_common.yaml directly, or adding special automation rules. I don't have any particular solutions for this at the ready, but some thoughts:

1. Solution does not modify source CAMARA_common.yaml: Solution needs to be added to release automation

   • Must assume placeholders are removed or Generic error responses have been amended/extended with domain-specific enums and examples.
   • Release automation must define validation rules for compatibility with a tagged CAMARA_common.yaml over exact match
     • Example: Allow adding INVALID_NETWORK_IDENTIFIER to Generic400's code enum, but disallow removing INVALID_ARGUMENT

2. Solution modifies how error responses are defined/consumed in future Commonalities release

   • Remove placeholders, GenericXXX errors are no longer extended directly. API's use OpenAPI extension mechanisms (e.g., allOf) to "inherit" GenericXXX and domain-specific extensions live in the domain API

In addition to the suggestions from @clundie-CL , can we also consider a handlebar/mustache template action, to replace placeholders in the API and Test definitions?

@Kevsy Perhaps your comment aligns with the issue I've described here? Template actions could potentially handle placeholder resolution/removal during the bundling stage, which would support Solution 1.

CC: @camaraproject/capabilities-and-runtime-restrictions_codeowners @camaraproject/network-access-management_codeowners @camaraproject/edge-cloud_codeowners

[Kevsy]

Thanks @clundie-CL for the helpful analysis -

@Kevsy Perhaps your comment aligns with the issue I've described here? Template actions could potentially handle placeholder resolution/removal during the bundling stage, which would support Solution 1.

Yes it does, thanks. Regarding placeholders in the Commonalities CAMARA_common.yaml: I think solution 1 should be able to support a repository making a local copy and then making the appropriate placeholder substitutions. 'Must assume placeholders are removed or Generic error responses have been amended/extended with domain-specific enums and examples.' should not exclude the result being validated, i.e. we know the rules by which placeholders are substituted, and hence can check that they were followed in the local copy.

Source for Local Copy
The exact match validation implies that API's MUST copy CAMARA_common.yaml from a specific release tag (e.g., r3.4) and not main. This ensures stable, versioned schemas during development and aligns with the release-plan.yaml dependency declaration (which specifies a release tag, not main)

And that answers my other comment regarding the source :)

[hdamker]

@clundie-CL @Kevsy

I don't think that there should be placeholders in the Generic400 response at all. Currently the CAMARA_common.yaml is exemplary, but not yet finally designed to be consumable via $refs in actual API definitions. We need some changes in this file before it is usable for this.

Two examples for that:

• currently the file pretends to be a complete API. It should focus on providing components (and possible responses if they are referable as is, but I have not the knowledge what can be referenced vs can't). The template structure of an API should be provided independent of that, referencing then the elements from CAMARA_common.yaml (so also showing how to use them).
• If there is an API specific error code it is no longer the "Generic400" response, but an extended and specific one for the API. The placeholder is nice for documentation, but not for reuse via reference. . The current "{{SPECIFIC_CODE}}" entry does not make sense ... the automation does not now what this SPECIFIC_CODE will be, and more important, there could be none, one, two or more API specific codes. Potentially Generic400 should be defined as a component instead a response which then referenced in the responses section of the API (and potentially extended)

The structure of Commonalities must be in a form that if the files are copied into the API Repository structure can be used without modifications locally in the API repositories.

With the in the report proposed structure directory it could be:

/artifacts
  /API_templates
      example-api.yaml   
  common/
     CAMARA_common.yaml
     ...  

Where example-api.yaml is the frame of an API definition with the mandatory sections using $refs ../common/CAMARA_common.yaml/...
With that we can also provide guidance HOW to consume CAMARA_common.yaml in APIs.

cc: @rartych

[hdamker]

@clundie-CL

Local Bundling for Development Preview

One practical consideration: if bundled YAMLs are not committed to main, developers who want to preview the API in rendered form (Redocly, Swagger UI) will need to run the bundling tool locally. This is a minor workflow addition, but we may need to consider documenting in contribution guidelines.

For local development you are right (we can provide a script for that), for validation runs in GitHub the bundled version can/will be uploaded within the workflow artifacts and can be downloaded from there. On the release snapshot branches it is directly accessible.

Implementation Details

I like the idea that release automation handles validation of the "local copy" against the intents described in the release-plan.yaml. However I think there's a couple of wrinkles to iron out.

Source for Local Copy

The exact match validation implies that API's MUST copy CAMARA_common.yaml from a specific release tag (e.g., r3.4) and not main. This ensures stable, versioned schemas during development and aligns with the release-plan.yaml dependency declaration (which specifies a release tag, not main).

Recommendation: Make this clear in the guidance text that is added to guidelines.

The copy shouldn't be done manually but by automation when pushing changes to the release-plan.yaml. It should be considered only as cache (no edits at all).

One practical concern: CAMARA_common.yaml contains examples with placeholders (e.g., code: "{{SPECIFIC_CODE}}"). While the syntax is valid, these placeholders are meant to be replaced in API definitions. This creates a conflict:

• If an API keeps the placeholders in their local copy → propagate to the API specification
• If an API removes/replaces them → "exact match validation" fails

CAMARA_common.yaml should not contain placeholders IMHO ... templates for APIs can. See my previous comment.

• Remove placeholders, GenericXXX errors are no longer extended directly. API's use OpenAPI extension mechanisms (e.g., allOf) to "inherit" GenericXXX and domain-specific extensions live in the domain API

That would spontaneously my preferred solution.

[PedroDiez]

@clundie-CL @Kevsy

I don't think that there should be placeholders in the Generic400 response at all. Currently the CAMARA_common.yaml is exemplary, but not yet finally designed to be consumable via $refs in actual API definitions. We need some changes in this file before it is usable for this.

Two examples for that:

• currently the file pretends to be a complete API. It should focus on providing components (and possible responses if they are referable as is, but I have not the knowledge what can be referenced vs can't). The template structure of an API should be provided independent of that, referencing then the elements from CAMARA_common.yaml (so also showing how to use them).
• If there is an API specific error code it is no longer the "Generic400" response, but an extended and specific one for the API. The placeholder is nice for documentation, but not for reuse via reference. . The current "{{SPECIFIC_CODE}}" entry does not make sense ... the automation does not now what this SPECIFIC_CODE will be, and more important, there could be none, one, two or more API specific codes. Potentially Generic400 should be defined as a component instead a response which then referenced in the responses section of the API (and potentially extended)

The structure of Commonalities must be in a form that if the files are copied into the API Repository structure can be used without modifications locally in the API repositories.

With the in the report proposed structure directory it could be:

/artifacts
  /API_templates
      example-api.yaml   
  common/
     CAMARA_common.yaml
     ...  

Where example-api.yaml is the frame of an API definition with the mandatory sections using $refs ../common/CAMARA_common.yaml/... With that we can also provide guidance HOW to consume CAMARA_common.yaml in APIs.

cc: @rartych

Yes, we agree we should take out placeholders in CAMARA_common.yaml and document (if more clarification needed, just as comment in CAMARA_common.yaml or in API design guide that new codes can be defined)

[PedroDiez]

As a comment regarding this:

CAMARA_common.yaml should not contain placeholders IMHO ... templates for APIs can. See my previous comment.

• Remove placeholders, GenericXXX errors are no longer extended directly. API's use OpenAPI extension mechanisms (e.g., allOf) to "inherit" GenericXXX and domain-specific extensions live in the domain API

In other projects we have used that formula, (we have some "common.yaml" in the same repo as the APIs and a building procedure that resolve the references:

For instance, case where we define a combined model error for an API scenario (use generic names for illustrating it):

    Error403ResponseModel:
      description: |-
        Client does not have sufficient permission.
        In addition to regular scenario of PERMISSION_DENIED to handle general permission restriction, another scenario may exist:
          - API_NAME.SPECIFIC_CODE: xxx
      headers:
        x-correlator:
          $ref: '#/components/headers/x-correlator'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error403ResponseModelSchema'
          examples:
            Example:
              value:
                code: PERMISSION_DENIED
                message: Authenticated user has no permission to access the requested resource

    Error403ResponseModelSchema:
      allOf:
        - $ref: '#/components/schemas/ModelError'
        - type: object
          required:
            - code
          properties:
            code:
              type: string
              enum:
                - PERMISSION_DENIED
                - API_NAME.SPECIFIC_CODE
              default: PERMISSION_DENIED
              description: Authenticated user has no permission to access the requested resource.

    ModelError:
      $ref: ../../common/components.yaml#/$defs/schemas/CommonModelError

CommonModelError:
  type: object
  required:
    - status
    - code
    - message
  properties:
    status:
      type: integer
      description: HTTP response status code
    code:
      type: string
      description: A human-readable code to describe the error
    message:
      type: string
      description: A human-readable description of what the event represents

[clundie-CL]

@hdamker @PedroDiez @Kevsy

Thank you for the detailed discussion and consensus on the path forward. The solution of removing placeholders from CAMARA_common.yaml and providing consumable components with extension examples is cleaner than the compatibility validation approach I initially considered. The following seeks to capture a rough summary of what has been discussed, informally agreed upon, and next steps.

Remaining Work Items

To operationalize this solution, I see several areas that need attention:

1. Changes to CAMARA_common.yaml

Placeholder Removal:

• Remove {{SPECIFIC_CODE}} and similar placeholders from error responses
• Update Generic error responses to contain only truly generic codes/examples

Linting Compliance:

• Address linting issues that arise when APIs consume the file via $ref
• Example issue: Comments not aligned at same indentation level as relevant fields (causes linting errors in consuming APIs)
• Ensure the file passes standard linters (Spectral, Redocly) when referenced

2. Commonalities Repository Structure for schema consumption

Per @hdamker's suggestion:

    code/
      API_definitions/   # Source API definitions (using relative refs)
      common/            # Local copy of CAMARA_common.yaml
      modules/           # (Optional) Project-specific local modules
    ```RA_common.yaml     # Pure, reusable components (no placeholders)

Where example-api.yaml shows:

• Referencing Generic responses via $ref
• Extending Generic responses using allOf for domain-specific codes
• Proper directory structure for main branch development

3. Documentation Updates

Section 2.1 of API Design Guide should clarify:

• How APIs consume schemas from CAMARA_common.yaml (via local copy + $ref)
• That local copies are sourced from specific release tags (per release-plan.yaml)
• That local copies are managed by CI automation (treated as cache, no manual edits)
• Extension pattern using allOf for domain-specific error codes

Pilot Volunteers

NetworkAccessManagement and Capabilities and Runtime Restrictions APIs are willing to serve as pilots for validating:

• The local copy + bundling workflow
• CI automation for syncing CAMARA_common.yaml from Commonalities tags
• Extension patterns for domain-specific error responses
• Integration with release automation

Timeline Concerns

A critical dependency: if the bundling approach is integrated with release automation targeting Fall '26 meta-release, the CAMARA_common.yaml changes (placeholder removal, linting fixes, structure reorganization) would need to be included in the Spring '26 Commonalities release?

Questions:

1. Is Spring '26 Commonalities release still open for these changes?
2. If not, what's the earliest release that can accommodate them?
3. Should pilot APIs begin refactoring now using the proposed structure, or wait for Commonalities changes?

Looking forward to the next steps and how we can help move this forward.