doc(Usage of discriminator): polymorphism and inheritance

[patrice-conil]

Clarify things between polymorphis and inheritance.
Give preference on inheritance over polymorphism to simplify usage of Camara APIs from strongly typed languages.
Discourage usage of multiple inheritance.

[hdamker]

Supportive for the PR, just some corrections within the example suggested.

[jlurien]

As commented in camaraproject/QualityOnDemand#177, I think that the new model is not aligned with the way that inheritance is meant to be described in OAS3 as shown in all the examples in the spec, which include all objects composing the child object as elements of the allOf array. This is not multiple inheritance, as there is only one single base object, the one with the discriminator. These examples have not changed since the times of Swagger 2, so I guess they are representing what the authors of the spec meant.

Problems with some generators and languages may happen, but they are limitations of the tools, not the spec or coding language. We have no guarantee that other tools may complain with the new model, and it is safer to be as close to official specification as possible.

In particular, if you use openapi-generator with Java, there was this known limitation, submitted indeed as bug many years ago. In this thread the model you proposed here is also proposed there as a mitigation. BTW, it seems that they have finally solved the root cause, as recently as 3 weeks ago,

[patrice-conil]

@jlurien,
I'm not the only one interpreting it as multiple inheritance as the guys at openapi-generator also translated it that way but it's probably a better idea to follow the examples in the spec to the letter. I will also fix it in QoD and Device Status proposals.

[hdamker]

/LGTM

[shilpa-padgaonkar]

@patrice-conil : I am currently in the process of moving docs from wg to comm repo.

Could you kindly open an issue and this PR in the new repo, once my housekeeping activity is done? We agreed in the last commonalities meeting that after PR #244 has been merged, we will only start new PRs in the new repo https://github.com/camaraproject/Commonalities.

If I simply merge your PR now with 1 approval, this will not allow other interested members from commonalities a chance to review your PR.

Regret the inconvenience.

[patrice-conil]

Hi @shilpa-padgaonkar ,
Sorry to have missed this point, I will move this PR to the new repository.

Regards

[shilpa-padgaonkar]

Thanks a lot @patrice-conil for your support. I will close this PR now and will look forward to your PR in the new comms repo soon!

[patrice-conil]

Hi Shilpa, Do you know this doc https://docs.github.com/en/repositories/creating-and-managing-repositories/duplicating-a-repository ? It may help moving files from old repo to new one. Hope this helps Patrice De : Shilpa Padgaonkar ***@***.***> Répondre à : camaraproject/WorkingGroups ***@***.***> Date : mardi 4 juillet 2023 à 09:26 À : camaraproject/WorkingGroups ***@***.***> Cc : CONIL Patrice INNOV/IT-S ***@***.***>, Mention ***@***.***> Objet : Re: [camaraproject/WorkingGroups] doc(Usage of discriminator): polymorphism and inheritance (PR #255) @patrice-conil<https://github.com/patrice-conil> : I am currently in the process of moving docs from wg to comm repo. Could you kindly open an issue and this PR in the new repo, once my housekeeping activity is done? We agreed in the last commonalities meeting that after PR #244<#244> has been merged, we will only start new PRs in the new repo https://github.com/camaraproject/Commonalities. If I simply merge your PR now with 1 approval, this will not allow other interested members from commonalities a chance to review your PR. Regret the inconvenience. — Reply to this email directly, view it on GitHub<#255 (comment)>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/AELO5GI7PGNH5JRFX52MPE3XOPASPANCNFSM6AAAAAAZ2AYDSU>. You are receiving this because you were mentioned.Message ID: ***@***.***>

…

____________________________________________________________________________________________________________ Ce message et ses pieces jointes peuvent contenir des informations confidentielles ou privilegiees et ne doivent donc pas etre diffuses, exploites ou copies sans autorisation. Si vous avez recu ce message par erreur, veuillez le signaler a l'expediteur et le detruire ainsi que les pieces jointes. Les messages electroniques etant susceptibles d'alteration, Orange decline toute responsabilite si ce message a ete altere, deforme ou falsifie. Merci. This message and its attachments may contain confidential or privileged information that may be protected by law; they should not be distributed, used or copied without authorisation. If you have received this email in error, please notify the sender and delete this message and its attachments. As emails may be altered, Orange is not liable for messages that have been modified, changed or falsified. Thank you.

[shilpa-padgaonkar]

@patrice-conil : Thanks a lot for your link :)
Yes, I am aware of mirroring, and we use it between our internal repo and provider implementation repo for QoD.
However, the working group repo is a mix of lot of things in addition to commonalities and in addition I wanted to do some cleanup and restructuring along the way.
But now it's almost done. I am just waiting to get the PR merged :)