5B Availability and distribution of OpenAPI specification files

As described in the clause 5.3.1 of 3GPP TS 29.501 [6], 3GPP Technical Specifications describing an API or common data types shall include an annex documenting the corresponding OpenAPI specification file.

For a TS agreed by the WG to be sent to TSG for approval to come under change control, the responsible MCC officer, in preparing that version (normally v2.0.0) shall, in conjunction with its rapporteur, check that the OpenAPI specification file(s) is(are) syntactically correct. This exercise should be accomplished in time to meet the deadline for submission of TDocs to the TSG plenary meeting. If errors are detected at this stage, the rapporteur should ask delegates to raise corrective pCR(s) to be sent directly to the TSG to correct the draft TS. The TSG shall be requested to approve both the draft TS and any such pCRs as a package, and if the package is approved, MCC shall incorporate those pCRs into the TS when preparing the first under-change-control version.

Prior to a TSG plenary meeting, the responsible MCC officer shall prepare CR Packs for all WG-agreed CRs in the usual manner. For those CRs which change the OpenAPI specification file(s) of the TS, the MCC officer and/or the rapporteur shall perform a trial implementation of those CRs which affect the OpenAPI specification file(s), and again check that the resulting specification file(s) is(are) syntactically correct. If errors are detected at this stage, the rapporteur should request authors of problematic CRs to provide corrective revisions of those CRs to be sent directly to the TSG as company contributions. The TSG shall be asked to approve all WG-agreed CRs for which no problems were detected plus the company revision CRs addressing the problematic ones. Ideally, not only the CR Packs containing the original WG-agreed CRs but also the revised, company-provided, CRs should be provided in time to meet the deadline for submission of TDocs to the TSG plenary meeting.

Before making available any new version of a TS containing an OpenAPI specification file, the responsible MCC officer shall extract the (syntax checked and verified) OpenAPI specification file from the annex of the TS and make it available as a stand-alone file in UTF-8 format as specified in IETF RFC 3629 [7]. The file name shall follow the conventions defined in 3GPP TS 29.501 [6] clause 5.3.6 unless the TS containing an OpenAPI specification file indicates a different file name.

If a new version of a TS containing an OpenAPI specification file is approved without any change to the contained OpenAPI specification file(s), the responsible MCC officer shall not modify the existing UTF-8 formatted OpenAPI specification file.

All the UTF-8 formatted OpenAPI specification files documented by TS shall be stored by the MCC officer in the following locations:

• https://forge.3gpp.org/rep/all/5G_APIs, and
• in the zip file containing the Word file of the new version of the TS (which is itself stored in the usual places).