Link between OpenAPI operation identifiers and 3GPP services

[p1-bmu]

First, thanks for providing this up-to-date repository !

I am trying to match the defined operations from the OpenAPI definitions to the 3GPP functional services definitions. In some yaml file, the keyword operationId seems well used, as in TS29518_Namf_Communication.yaml.
However, in some other yaml files, this looks completely messed up, as in TS29508_Nsmf_EventExposure.yaml, where 4 operations have the following ids: CreateIndividualSubcription, DeleteIndividualSubcription, GetIndividualSubcription and ReplaceIndividualSubcription ; but the TS 23.502 and TS 29.508 define the 4 following service operations: Subscribe, Unsubscribe, Notify and AppRelocationInfo, where the 2 last correspond in the yaml file to callbacks without operationId actually set...

Do you know if there is an intention to have this made more reliable during the next 3GPP meetings, or if this operationId keyword is just cosmetic and will never match perfectly the 3GPP service definitions ?

[jdegre]

Hi @p1-bmu, thanks for sharing your feedback!

The operationId attributes have been assigned in most APIs with no actual linking to the "stage-2" specs (e.g. TS 23.502).

They have been following an approach to be simply descriptive strings identifying uniquely each operation (mainly to be used by tools/libraries as indicated in the OpenAPI spec, but also where they might potentially be used along with Link objects in some APIs).

In any case, it is true that there are APIs where this info is missing, in parcitular in callback operations, and yes, there is an intention to make the appropriate corrections in coming meetings.

[p1-bmu]

Thank you for your quick feedback.

As I understand, there is the intention that have systematic / explicit operationId set for most of the operations, but those ids may not match with service operations naming used in 3GPP TS (such as those defined in TS23.502, e.g. in section 5.2).

Aside from this, I noted that 2 operations may have the same operationId, whereas the OpenAPI specification suggests those operationId to uniquely identify a single operation (these IDs must be unique among all operations described in your API):

• TS29551_Nnef_PFDmanagement.yaml, operationId Nnef_PFDmanagement_Fetch identifies multiple operations:
  • ('/applications', 'get')
  • ('/applications/{appId}', 'get')
• TS29551_Nnef_PFDmanagement.yaml, operationId Nnef_PFDmanagement_Subscribe identifies multiple operations:
  • ('/subscriptions', 'post')
  • ('/subscriptions/{subscriptionId}', 'put')
• TS29518_Namf_Communication.yaml, operationId N2InfoNotify identifies multiple operations:
  • ('/ue-contexts/{ueContextId}', 'put', 'callbacks', 'onN2MessageNotify', '{$request.body#/n2NotifyUri}', 'post')
  • ('/ue-contexts/{ueContextId}/n1-n2-messages/subscriptions', 'post', 'callbacks', 'onN1N2MessageNotify', '{$request.body#/n2NotifyCallbackUri}', 'post')

[p1-bmu]

I'll let you close the issue if you want, as your initial answer was fine to me. But maybe you want to keep it open to track it further.

[jdegre]

I think it's better to keep it open, as you said, for easier tracking and as a reminder for me to trigger the corresponding corrections at next 3GPP meeting :)