Use of placeholders in CAMARA artefacts

[Kevsy]

Problem description

Release number and version are manually added to CAMARA artefacts (.yaml, .md) by the authors. This adds time and risks values being incorrect, inconsistent, or updates missed.

There are also examples where these values are in documentation (e.g. camaraproject/Commonalities#457 ) , again requiring manual update.

Possible evolution

Investigate the use of placeholders for release number and version within artefact files, and a GitHub Action that:

• replaces the placeholders with the correct values on commit
• automatically generates a PR with the placeholder values updated

Note: the means to determine 'correct values' is to be investigated. This could be automated or may need to be a parameter manually injected at the point of the Action workflow being run.

Alternative solution

• Recommend placeholder update in VS Code (the most popular IDE in our poll) prior to commit

Additional context

[hdamker]

@Kevsy I would very much like to see an approach with placeholders and automated replacement of them. But I have some difficulties to understand how that would look like, maybe you can explain it a bit.

My thoughts:

If there only one file with the API definition as today, the placeholders are replaced after the first run of the automation and committed into main => there are no placeholder any more after the first commit.

We would need to work with a source file (with placeholders in the appropriate places), which is the one which will be changed, and then a resulting API definition file which will be always automated created by this. Such approach would be extendable to add the standard info.description texts, resolve reference to CAMARA_common.yaml etc. I suppose it can be also introduced stepwise (with a template for new APIs, some script to create the source from existing API definitions, leaving it to the projects when to switch to the new approach).

But maybe I have misunderstood your proposal in this issue and it's only about first time an artifact will be integrated into the API definition.

[Kevsy]

Thanks @hdamker -

But maybe I have misunderstood your proposal in this issue and it's only about first time an artifact will be integrated into the API definition.

No, you have it right in the first paragraph - the idea is to simplify the updates for all iterations. But as you say, only the first build would have an unresolved placeholder. Subsequent builds would have values populated, so we would need to grep for the value to be updated (they are not uniquely accessible from a YAML key value pair).

Some considerations:

1. For the OAS YAML: OAS 3.0 unfortunately removed the placeholder capability ('definitions') that was in OAS 2.0.
2. $ref is not resolved in string blocks and is anyway not well supported by SDK generators where the $ref is to an external file
3. Replacing placeholders is done post-commit, but won't update that commit.

My current thinking is that a sed action to perform replacements of the variable values could fix considerations 1 and 2, and an Action that generates a new PR from the values-updated commit could solve 3.

For the templates from Commonalities and Identity and Consent Management: we could utilise invisible HTML comments within info.description to indicate the start/end of these blocks.

I'll test some of these concepts in my personal repo...