Open APIs

I found some errors in your openapi spec TMF931-Open_Gateway_Operate_API_-_Onboarding_and_Ordering-v5.1.1.oas.yaml
I can contribute to your project if you allow

• Typos: focusses, authentification, whished, retreive, timeOccurred, commertial
• Property 'deprecated' is not allowed
• ProductOrderStateType.enum.inProgress.accepted
• ProductStatusType.enum.'aborted '
• IETC-RFC-3339 format is correctly called IETF -RFC-3339 (Internet Engineering Task Force)
• double underscore in the property name (for example Create_a_API_Product_Order_for_ordering_modify_a_new_product__request) breaks generation via openapi-generator for kotlin
• 201Monitor, 200ApiProductOrder_Patch, 200ApiProduct_Patch, 201ApiProduct are never used
• this discussion assumes that _FVO entities for POST request bodies, then some entities do not have _FVO representation or contain properties with type not _FVO (for example PartyRoleRef_FVO inherit EntityRef). please clearly define what _FVO and _MVO are and their use
• confusing properties overrides (for example Addressable has id, href properties, EntityRef inherit Addressable but has it's own id, href, while Event has it's own id and href and doesn't inherit)
• single implementation discriminator (most entities have a discriminator on themselves) some languages ​​in openapi-generator can't resolve such discriminator
  it would be great if you could check the generation (because sample implementation code doesn't work)
• properties with @ (for example @type) in their name are generated as at prefixed (atType) it would be much easier and more convenient if you change them as just a type
• unconventional names (for example ApiProductDeviceLocationVerification_example; ProductOrderItemDelete, but others start with Api prefix)
• mapping itself in implementations (for example ContactMedium.discriminator.mapping contains itself) this breaks inheritance for some openapi-generator languages
• extra inheritance element (for example DCSProductOrderItem inherits GCProductOrderItem but does not contain anything and is not used anywhere) besides mapping itself in implementations
• incorrect polymorphism (for example AttachmentRefOrValue inherit oneOf: Attachment or AttachmentRef and has mapping, but each of them must have allOf from the AttachmentRefOrValue) kotlin openapi-generator can't resolve your oneOf polymophism

Hi Pavel

Thanks for the feedback.  Maybe @Olivier Arnaud can comment on some of these issues?

Regards

I found some errors in your openapi spec TMF931-Open_Gateway_Operate_API_-_Onboarding_and_Ordering-v5.1.1.oas.yaml
I can contribute to your project if you allow

• Typos: focusses, authentification, whished, retreive, timeOccurred, commertial
• Property 'deprecated' is not allowed
• ProductOrderStateType.enum.inProgress.accepted
• ProductStatusType.enum.'aborted '
• IETC-RFC-3339 format is correctly called IETF -RFC-3339 (Internet Engineering Task Force)
• double underscore in the property name (for example Create_a_API_Product_Order_for_ordering_modify_a_new_product__request) breaks generation via openapi-generator for kotlin
• 201Monitor, 200ApiProductOrder_Patch, 200ApiProduct_Patch, 201ApiProduct are never used
• this discussion assumes that _FVO entities for POST request bodies, then some entities do not have _FVO representation or contain properties with type not _FVO (for example PartyRoleRef_FVO inherit EntityRef). please clearly define what _FVO and _MVO are and their use
• confusing properties overrides (for example Addressable has id, href properties, EntityRef inherit Addressable but has it's own id, href, while Event has it's own id and href and doesn't inherit)
• single implementation discriminator (most entities have a discriminator on themselves) some languages ​​in openapi-generator can't resolve such discriminator
  it would be great if you could check the generation (because sample implementation code doesn't work)
• properties with @ (for example @type) in their name are generated as at prefixed (atType) it would be much easier and more convenient if you change them as just a type
• unconventional names (for example ApiProductDeviceLocationVerification_example; ProductOrderItemDelete, but others start with Api prefix)
• mapping itself in implementations (for example ContactMedium.discriminator.mapping contains itself) this breaks inheritance for some openapi-generator languages
• extra inheritance element (for example DCSProductOrderItem inherits GCProductOrderItem but does not contain anything and is not used anywhere) besides mapping itself in implementations
• incorrect polymorphism (for example AttachmentRefOrValue inherit oneOf: Attachment or AttachmentRef and has mapping, but each of them must have allOf from the AttachmentRefOrValue) kotlin openapi-generator can't resolve your oneOf polymophism

Hi @Pavel Zdanovich (and thanks @Dan d'Albuquerque for notification)

thanks a lot for this very precise feedback. Of course you can contribute to this work if you're employee of a TMF Member company (I don't see Vonage in the list :Current members - TM Forum). We are organised in a working group, we have 2 meetings per week and some yearly in-person workshops. Tell me if you would like to join.

Regarding your comments, I'll try to answer as much as possible. Please Don't wait for immediate fixes, some fixes can be applied on a future minor version, some may be done on a potential v6 major version (for non backward compatible changes, or structural changes) but we don't have any roadmap yet for the v6 generation, and some may never be fixed because they are choices assumed even if there are drawbacks.

- Typos: focusses, authentification, whished, retreive, timeOccurred, commertial -> ok, Added in a JIRA https://projects.tmforum.org/jira/browse/AP-6454 

- Property 'deprecated' is not allowed -> do you mean that it's not applicable as described here : https://spec.openapis.org/oas/v3.0.3#fixed-fields-19 ? Even if the description in the OAS specification is not very clear, it appears well in swagger editor, without errors. Please precise the issue.

- ProductOrderStateType.enum.inProgress.accepted -> what is the issue ? This enum list comes from the standard TMF622 API list. An evolution could be to restrict to the only needed values in this Open Gateway context, proposed here https://projects.tmforum.org/jira/browse/AP-6174

- ProductStatusType.enum.'aborted ' -> Ok, added in https://projects.tmforum.org/jira/browse/AP-6174

- IETC-RFC-3339 format is correctly called IETF -RFC-3339 (Internet Engineering Task Force) -> ok, added in https://projects.tmforum.org/jira/browse/AP-6454

- double underscore in the property name (for example Create_a_API_Product_Order_for_ordering_modify_a_new_product__request) breaks generation via openapi-generator for kotlin -> ok, new issue raised to the tooling team to not generate double underscore and added in https://projects.tmforum.org/jira/browse/AP-6174. Could you precise the error raised by Kotlin ? is it a blocking error or a warning ?

- 201Monitor, 200ApiProductOrder_Patch, 200ApiProduct_Patch, 201ApiProduct are never used -> known issue, raised to tooling team, will be fixed soon (for all TMF API)

- this discussion assumes that _FVO entities for POST request bodies, then some entities do not have _FVO representation or contain properties with type not _FVO (for example PartyRoleRef_FVO inherit EntityRef). please clearly define what _FVO and _MVO are and their use -> this has been a decision that applies for all TMF API, can't be changed just for this API. There are some changes in the tooling, new generated OAS should be more precise. There is also an open issue to document this at least in the User Guide. And also a issue to propose simplification in the generated OAS avoiding those duplications.

- confusing properties overrides (for example Addressable has id, href properties, EntityRef inherit Addressable but has it's own id, href, while Event has it's own id and href and doesn't inherit) -> ok, EntityRef should not inherit from Addressable. JIRA created https://projects.tmforum.org/jira/browse/AP-6477

- single implementation discriminator (most entities have a discriminator on themselves) some languages ​​in openapi-generator can't resolve such discriminator -> it is under discussion with tooling team. The general reason is that all schemas inheriting from Extensible can be specialized. In that case the discriminator is mandatory. So the discrimininator is always put by default. to allow extension ot the possible values Could you tell me which languages can't resolve this ? Because this definition is compatible with OAS specification, so maybe it's an issue in the open api generators ?

- it would be great if you could check the generation (because sample implementation code doesn't work) -> agree, we should do it for next releases

- properties with @ (for example @type) in their name are generated as at prefixed (atType) it would be much easier and more convenient if you change them as just a type -> this has been a decision that applies for all TMF API, can't be changed just for this API. There have been hours of discussions on this topic, so we'll not raise it again.

- unconventional names (for example ApiProductDeviceLocationVerification_example; ProductOrderItemDelete, but others start with Api prefix) -> this is normal. ApiProductDeviceLocationVerification_example exist only for giving an example of a strongly typed schema of ApiProduct that is present in the OAS, so the "_example" shows that it has not to be implemented; all further strongly typed ApiProduct schemas might be available on a json schema repository. Regarding ApiProductOrderItemAdd and ApiProductOrderItemModify they exist because they contain specific attributes on this context whereas the ProductOrderItemDelete don't (so no need for Api prefix). I agree we should avoid these prefixes and use common schemas for following versions, it is added in this JIRA https://projects.tmforum.org/jira/browse/AP-6174. This is the first specialized TMF API that is being implement in production, so we know we made some choices that are now challenged because we made some progess since.

- mapping itself in implementations (for example ContactMedium.discriminator.mapping contains itself) this breaks inheritance for some openapi-generator languages -> isn't it same question as above "single implementation discriminator..." ?

- extra inheritance element (for example DCSProductOrderItem inherits GCProductOrderItem but does not contain anything and is not used anywhere) besides mapping itself in implementations -> agree, this was a directive for DCS (Domain Context Specialization) API, but I don't think it is useful, it is added in this JIRA https://projects.tmforum.org/jira/browse/AP-6174

- incorrect polymorphism (for example AttachmentRefOrValue inherit oneOf: Attachment or AttachmentRef and has mapping, but each of them must have allOf from the AttachmentRefOrValue) kotlin openapi-generator can't resolve your oneOf polymophism -> I don't understand your comment, could you precise ? I don't see the issue.

Hi Pavel

Thanks for the feedback.  Maybe @Olivier Arnaud can comment on some of these issues?

Regards

I found some errors in your openapi spec TMF931-Open_Gateway_Operate_API_-_Onboarding_and_Ordering-v5.1.1.oas.yaml
I can contribute to your project if you allow

• Typos: focusses, authentification, whished, retreive, timeOccurred, commertial
• Property 'deprecated' is not allowed
• ProductOrderStateType.enum.inProgress.accepted
• ProductStatusType.enum.'aborted '
• IETC-RFC-3339 format is correctly called IETF -RFC-3339 (Internet Engineering Task Force)
• double underscore in the property name (for example Create_a_API_Product_Order_for_ordering_modify_a_new_product__request) breaks generation via openapi-generator for kotlin
• 201Monitor, 200ApiProductOrder_Patch, 200ApiProduct_Patch, 201ApiProduct are never used
• this discussion assumes that _FVO entities for POST request bodies, then some entities do not have _FVO representation or contain properties with type not _FVO (for example PartyRoleRef_FVO inherit EntityRef). please clearly define what _FVO and _MVO are and their use
• confusing properties overrides (for example Addressable has id, href properties, EntityRef inherit Addressable but has it's own id, href, while Event has it's own id and href and doesn't inherit)
• single implementation discriminator (most entities have a discriminator on themselves) some languages ​​in openapi-generator can't resolve such discriminator
  it would be great if you could check the generation (because sample implementation code doesn't work)
• properties with @ (for example @type) in their name are generated as at prefixed (atType) it would be much easier and more convenient if you change them as just a type
• unconventional names (for example ApiProductDeviceLocationVerification_example; ProductOrderItemDelete, but others start with Api prefix)
• mapping itself in implementations (for example ContactMedium.discriminator.mapping contains itself) this breaks inheritance for some openapi-generator languages
• extra inheritance element (for example DCSProductOrderItem inherits GCProductOrderItem but does not contain anything and is not used anywhere) besides mapping itself in implementations
• incorrect polymorphism (for example AttachmentRefOrValue inherit oneOf: Attachment or AttachmentRef and has mapping, but each of them must have allOf from the AttachmentRefOrValue) kotlin openapi-generator can't resolve your oneOf polymophism