Consolidate Common Data Types into a single YAML-File

[maxl2287]

Problem Description Currently, we are sometimes using the same data types and components in different API specifications. This issue has arisen after splitting the device-status.yaml into separate YAML files (see #161 and #152).

Components such as Device, ErrorInfo, SubscriptionId, etc., are duplicated and reused across these specifications.

Example If we need to change a pattern, such as for the phoneNumber, it requires updating every instance of the PhoneNumber component.

Possible evolution

We should follow the option outlined in the API-Design Guidelines and create a separate YAML file for common CAMARA data types.

[akoshunyadi]

Already there: https://github.com/camaraproject/Commonalities/blob/main/artifacts/CAMARA_common.yaml

[maxl2287]

@akoshunyadi yes, I know. So we can use it here right?

[akoshunyadi]

Yes ... however it's not clear for me, if there's a hint for the usage. I mean, using it as a reference at the original location, or copy it to the main yaml and reference it with relative path.

[maxl2287]

So my intention is here to extract our common components of the DeviceStatus-API next to the specifications into an own common-data-types.yaml or something similiar.

[shilpa-padgaonkar]

@maxl2287 Thanks for taking this up. Would be great though if this lands in the commonalities artifact CAMARA_common.yaml

[maxl2287]

Hi @shilpa-padgaonkar, maybe I didn't understand your proposal well. What should be included in the CAMARA_common.yaml? I mean if I find something what could be common, I can add it as well in the Commonalities, of course.

My proposal is to have this common file (however we want to name it) placed next to the specifications and referenced from the specifications to the common components.

Structure

Using components from CAMARA_common.yaml

[shilpa-padgaonkar]

@maxl2287 : Everything is just as you have shown above, except that the common.yaml file resides in commonalities. You can see it in an example shown by @gmuratk in context of an old (now closed) issue.

[maxl2287]

Hi @shilpa-padgaonkar,

thanks for pointing this out. I need to check how this can work with the code-generators for provider-implementation. As of now we are facing some issues when using $ref with URL inside.

I will keep you informed.

[maxl2287]

Hi @shilpa-padgaonkar,

after investigating a lot on finding a possible solution with our code-generators, I came to the conclusion that I have not discovered any success.

Just to keep you informed, that a trial with an external URL in the $ref was not successful with our generator.

BR Max