Specifications shall be maintained in the form of computer-based files. The file name shall be of the form

• aabbb-xyz.eee

where:

• aa and bbb have the same significance as in the specification number (see tables 1 and 2);
• x, y and z have the same significance as in the version number (see table 6);
• eee is the de facto standard filename extension corresponding to the software tool used to create the file (normally "doc" for Microsoft Word ®).

For multi-part specifications, the filename shall be extended to

• aabbb-n-xyz.eee

Where:

• n is the part number (see tables 6 and 6A).

To save storage space and to speed up uploading and downloading, source files shall be saved compressed in industry standard "Zip" ® format. The filename of the zipped file shall be the same as that of the contained source file, and it shall bear the file extension ".zip". If a specification consists of multiple source files - for example, when a very long document is divided into several smaller files for ease of editing and manipulation - , each file should be named with the above convention, but appending a file identifier in the form:

• aabbb-xyz(m).eee

where:

• m is the file number using characters from table 6 or 6A.

Where a specification has accompanying files - e.g. ASN.1 coding, C programming language code, TTCN test sequences, etc. - it may not be convenient or possible to abide by the last-mentioned rule. Under these circumstances, the associated files shall be contained in a separate zip file, which shall itself abide by the multiple-source-file rule. A "readme" text file should be included in that zip file to explain the nature of each other file. EXAMPLE 1: EXAMPLE 2: EXAMPLE 3: EXAMPLE 4: Draft versions of specifications may be made available in the responsible Groups' directories. Such versions shall be clearly distinguishable from "official" versions by substituting "d" for the hyphen before the version code. Thus:

• aabbbdxyz.eee

(for example, 28033d410.zip). Such files shall never appear in the official specification directories. The foregoing file format using three characters for the version number is valid as long as none of the three version elements (major, technical, editorial) exceeds the value 35, since the characters 0..9, a..z represent a base-36 value. If any one or more of the three version elements exceeds 35 then the file format shall be modified to use two decimal characters in the range 00 to 99 for each element, i.e. six characters in all. EXAMPLE 5: Version 15.36.0 of TS 29.341 would have the file name 29341-153600. (The file extension is omitted for clarity.) For specification part and sub-part numbers, one or two characters may be used, 0..9 or 00..99. Ideally the intended number of parts and sub-parts should be known when the first specification numbers are allocated so that the correct number of digits can be used from the outset, ensuring that filenames are correctly sorted when listed. EXAMPLE 6: Part and sub-part numbers shall not use characters a..z, but shall always be one- or two-digit decimal values.

 

As described in the clause 5.3.1 of TS 29.501, 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 TS 29.501 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).

In this option, the normative code parts of the stage 3 specification shall be normatively stored in the 3GPP Forge repository. The TS document specifying the stage 3 definition shall indicate that the 3GPP Forge repository is normative for the corresponding stage 3 specification files and:

• The TS document shall contain a link to a 3GPP Forge repository tag that implicitly includes the versioning information about the TS, e.g. https://forge.3gpp.org/rep/sa5/MnS/-/tree/Tag_Rel18_SA100;
• The TS document shall contain the directory path where the files are stored, e.g. "yang-models";
• The TS document shall contain the name of the files specified by this TS;
• The TS document shall not contain a copy of the stage 3 specification files.

Before making available any new version of a TS specifying stage 3 files, the responsible MCC officer shall download the specification files from 3GPP Forge and store them in the zip file containing the new version of the TS document. This zip file shall be published in the usual places. All OpenAPI stage 3 specification files referenced by the TS document shall also be stored by the MCC officer in the following location:

• https://forge.3gpp.org/rep/all/5G_APIs.