Tech-invite3GPPspecsSIPRFCs
Overview21222324252627282931323334353637384‑5x

Content for  TR 21.900  Word version:  16.3.0

Top   Top   Up   Prev   Next
0…   4…   4.4…   5…   6…   7…   8…   9…

 

5  Availability and distribution of specifications

The Support Team shall make all approved versions of all specifications available as soon as possible after their approval (or after approval of CRs thereto) on a file server. The server shall allow anonymous access by any interested party.
The Support Team should also endeavour to make earlier drafts available on the server, even prior to approval, i.e. versions 0.y.z, 1.y.z and 2.y.z.
Such "availability" does not constitute formal "publication". Under the terms of the 3GPP partnership agreement, the Organizational Partners which are Standards Development Organizations will publish TSG-approved specifications in the form of their own standards. The modalities of such publication processes are specific to those individual Organizations and are beyond the scope of the present document.
The directory structure shall differentiate amongst approved and draft specifications, amongst versions of specifications approved at specific TSG meetings, amongst versions of specifications pertaining to different Releases, and between specifications relating to 2nd generation (GSM) only and 3rd generation (UMTS) systems.
A clear and unambiguous directory structure shall be adopted, and a guide to that structure provided on the server. A "status list" shall also be provided, showing the latest version of each Release of each specification.
Up

5A  File naming conventions

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:
29341-420.zip is the compressed file of specification 29.341 version 4.2.0.
EXAMPLE 2:
31811-m-6g2.doc is the source file of specification 31.811 part 22 version 6.16.2.
EXAMPLE 3:
22354-480(1).doc and 22354-480(2).doc are the two files which make up specification 22.354 version 4.8.0 (and which will both be compressed into file 22354-480.zip).
EXAMPLE 4:
34101-300(1).doc and 34101-300(2).zip are the source text file and the compressed set of TTCN files respectively which together comprise 34.101 version 3.0.0.
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.35.0 of TS 29.341 would have the file name 29341-fz0.
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:
Permissible filenames for multi-part specifications (file extensions omitted for clarity):
29341-1-5
29342-2-15
29343-13-21
29344-08-55
29345-19-6
Part and sub-part numbers shall not use characters a..z, but shall always be one- or two-digit decimal values.
Value
Character
Remarks

0
0
Only for use in version number fields. Part / sub-part numbers and file numbers start at 0 or 1 (or 00 or 01 - see table 6A).
1
1
2
2
3
3
4
4
5
5
6
6
7
7
8
8
9
9
10
a
11
b
12
c
13
d
14
e
15
f
16
g
17
h
18
i
19
j
20
k
21
l
22
m
23
n
24
o
25
p
26
q
27
r
28
s
29
t
30
u
31
v
32
w
33
x
34
y
35
z
Higher values - see table 6A.

 
Value
Character
Remarks

0
00
1
01
2
02
...
9
09
10
10
11
11
...
34
34
35
35
36
36
37
37
...
98
98
99
99
Higher values for further study if necessary

Up

5B  Availability and distribution of OpenAPI specification filesWord‑p. 27
As described in the subclause 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.etsi.org/rep/3GPP/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).
Up

Up   Top   ToC