[{"name":"SP-210025","title":"LS from SA WG5: LS on OpenAPI guidelines","source":"SA WG5","contact":"Thomas Tovinger","contact-id":3654,"tdoctype":"LS in","for":"Action","abstract":"At SA#90, SA WG5 received an official request from TSG CT (in the CT report to SA) to align with the OpenAPI guidelines developed by CT in 29.501. SA WG5 has analysed and discussed these comments extensively, also in a conf. call with CT, and a contribution summarising the request from CT was submitted to SA WG5#136e by the CT chair as S5-212235 (attached). SA WG5 has discussed the document and would like to provide the following feedback regarding the requests provided (main bullets in slides 3-5 of S5-212235): 1. 'As described in TR 21.900 clause 5B, All OpenAPI specification files documented by TS have to be stored by the MCC officer in the following locations.' SA WG5 reply: SA WG5 has some concerns to put all OpenAPI files into one repository. SA WG5 is actively cooperating with open source projects and the SA WG5 forge repository is already referred by external groups in their implementation. Changing the repository may cause problems and impact SA WG5 external influence. In addition, we would like some clarification on the rationale behind using one repository. One reason presented was simplification of referencing other OpenAPI files. We think this target may also be achieved by other means (please see bullet point 3). SA WG5 supports any endeavour to make 3GPP OpenAPI definitions easily accessible for the worldwide development community. We suggest working on a simplified branching strategy for outside exposure shielding external readers from 3GPP internals. We welcome a continued discussion with CT on this point. It is not an issue however for our MCC officer to store the files in the zip file containing the Word file of the new version of the TS; this can be done from the SA#91 CR implementation. 2. 'Align YAML file naming with TS 29.501 clause 5.3.6' SA WG5 reply: SA WG5 specifications contain an OpenAPI definition file name. SA WG5's understanding is that this approach is consistent with CT guidelines. 3. 'Align $refs in normative OpenAPI in TS's' SA WG5 reply: SA WG5 acknowledges that references need to be carefully designed. For example, 3GPP should ensure that the external development community can use the 3GPP definitions without the need to change them. References containing just the file name and no relative or absolute path components can help in that. SA WG5 proposes to enhance the 3GPP Forge environment with the possibility to specify locations where the tool shall search for referenced files. This would allow for using simple references with the file name only, also for the case that CT and SA WG5 use different repositories. 4. 'Align to 3GPP Common API Versioning Mechanism' SA WG5 reply: SA WG5 currently uses a versioning concept where the OpenAPI definition version number is identical to the TS version number containing the OpenAPI definition. We acknowledge that the CT concept which decouples the OpenAPI definition version number from the TS version number has advantages. We will study if it is possible to adopt the CT concept. 5. 'Align with IE naming convention' SA WG5 reply: SA WG5 guidelines and best practices are aligned with CT naming conventions in many cases: - Attribute names follow lowerCamel convention - Values of enumerations use UPPER_WITH_UNDERSCORE - Data type names follow UpperCamel convention - Array names are either plural ('users') or are appending 'List' ('userList'). Plural only can be used in future. - Query parameter names follow the same naming convention as attributes when they refer to attributes of the resource. CT uses lower-with-hyphen. SA WG5 believes readability is improved when attribute names and query names are identical when they refer to the same information. - URI path segment names follow lower-with-hyphen for standalone Management Services (MnS). For an MnS combined from an NRM and CRUD operations, the naming convention for managed object classes used in stage 2 (e.g. to align with RAN specifications) is also used for stage 3: normally UpperCamel is followed (e.g","secretary_remarks":"Proposed Action: Noted. Noted","agenda_item_sort_order":10,"ainumber":"2.2","ainame":"Incoming LSs which need an outgoing LS","tdoc_agenda_sort_order":10320,"status":"noted","reservation_date":"2021-02-27 15:44:51","uploaded":"2021-03-17 09:56:02","revisionof":"","revisedto":"","release":"Rel-16","crspec":"","crspecversion":"","workitem":"","crnumber":"","crrevision":"","crcategory":"","tsg_crp":"","lsreplyto":"","lsto":"TSG SA, TSG CT","Cc":"CT WG4, CT WG3","lsoriginalls":"S5-212312","lsreply":"","link":"https:\/\/www.3gpp.org\/ftp\/tsg_sa\/TSG_SA\/TSGs_91E_Electronic\/Docs\/SP-210025.zip","group":"SP","meeting":"SP-91-e","year":2021,"uicc_affected":null,"me_affected":null,"ran_affected":null,"cn_affected":null,"clauses_affected":null,"crsinpack":null,"crsinpacknumber":0}]