Tech-invite3GPPspaceIETFspace
21222324252627282931323334353637384‑5x

Content for  TS 33.128  Word version:  18.7.0

Top   Top   Up   Prev   Next
0…   4…   5…   5.7…   6…   6.2.2.2A…   6.2.3…   6.2.3.2.7…   6.2.3.3…   6.2.4…   6.3…   6.3.2.2A…   6.3.3…   6.3.3.2…   6.3.3.2.4…   6.3.3.2A…   7…   7.3…   7.3.3…   7.3.3.2.21…   7.3.3.2.42…   7.3.3.2.63…   7.3.4…   7.4…   7.4.3.8…   7.5…   7.6…   7.7…   7.7.4…   7.8…   7.8.4…   7.9…   7.10…   7.10.4…   7.11…   7.12…   7.13…   7.13.3…   7.13.3.4…   7.14…   7.15…   8…   A…   D…   E…   M…

 

D  Drafting Guidancep. 399

D.1  Introductionp. 399

This annex provides drafting guidance for contributors wishing to propose changes to the present document.

D.2  Drafting conventionsp. 399

Drafting conventions are described in Table D.2-1.
ID Description
D.2.1The details for each field, including a complete description of the usage, format, cardinality, and conditionality of that field, are given in the prose in the main body of the document.
When a table is used in the main body of the document to describe complex type (including CHOICE, SEQUENCE, or SET), the row order in the table matches the ASN.1 tag order.
D.2.2The field names used in the main body of the document match those used in the ASN.1.
D.2.3ASN.1 comments are not used, except to indicate:
  1. Where to find a description of the field or structure in the main body of the specification. Be aware that XIRIEvent and IRIEvent fields are usually described in separate clauses.
  2. When a tag is reserved for a purpose in an equivalent structure (see D.4.15) or a different Release, to avoid a potential tag conflict in the future.
  3. Where fields in XIRIEvent and IRIEvent for a given NF are continued from a previous disjoint tag number.
  4. When a field is deprecated (see D.2.5 and D.4.14).
ASN.1 comments are defined before an item, not after.
D.2.4If a field is made conditional, the condition for its presence or absence is specified.
D.2.5 When any field is deprecated, the table of main text is modified. The "Field" column is renamed to "deprecated{PreviousName}" (where {PreviousName} is previous name of the field with the first character in upper-case). The "Description" column is changed into "No longer used in present version of this specification".
When a mandatory field is deprecated, the "Description" column is also changed to specify a placeholder value. The value of the "Cardinality" column (if present) is not changed. The value of the "M/C/O" column is not changed.
When an optional field is deprecated, the value of "Cardinality" column (if present) is changed to "0". The value of the "M/C/O" column is not changed.
When a conditional field is deprecated, the value of "Cardinality" column (if present) is changed to "0". The value of the "M/C/O" column is set to "O".
When a field is deprecated, the ASN.1 field is renamed to deprecated{PreviousName} (see D.4.14). A comment is added before indicating the ASN.1 release and version that deprecated the field (see D.2.3). For example "deprecated{PreviousName} was deprecated in r18(18) version5(5)".
D.2.6When describing a field, where possible any references contain an explicit clause or section.
D.2.7 OCTET STRING fields encoding information elements that contain a leading type and length in their definition omit the type and length octets, and the table row of main text for the field contains "omitting the first N octets" to indicate this.
D.2.8 If a new required field is added to an existing SEQUENCE or SET, and the ASN.1 is OPTIONAL for backwards compatibility (see D.4.13), the table row of main text for the field contains "C" in the "M/C/O" column, and the "Description" column contains "Shall be provided." (or a more specific statement), and "This parameter is conditional only for backwards compatibility."
Up

D.3  Naming conventionsp. 400

ASN.1 naming conventions are described in Table D.3-1, and examples of naming conventions to avoid are shown in Figure 1.
ID Description
D.3.1To meet ASN.1 syntax rules, the first character of each ASN.1 field name are lower-cased.
D.3.2To meet ASN.1 syntax rules, the first character of an ASN.1 type name are upper-cased.
D.3.3To meet ASN.1 syntax rules, the first character of a field or a type name is not a number.
D.3.4Only the character ranges A-Z, a-z and 0-9 are used in names.
D.3.5Names are CamelCased, where the first character of each word is upper-cased (except for the first character of the name - see rule D.3.1).
D.3.6Any acronyms in a name are entirely upper-cased (except for the first character of the name - see rule D.3.1).
Figure 1 - Naming convention counter-examples
Up

D.4  ASN.1 Syntax conventionsp. 401

ASN.1 syntax conventions are described in Table D.4-1, examples of conformant ASN.1 syntax conventions are shown in Figure 2, and examples of ASN.1 syntax conventions to avoid are shown in Figure 3.
ID Description
D.4.1Modules are be defined with EXTENSIBILITY IMPLIED unless there is a specific reason to limit extensibility.
D.4.2The AUTOMATIC TAGS module directive is not used.
D.4.3SEQUENCE and CHOICE tag numbers start at one, and are allocated sequentially, except when tags are reserved for an equivalent structure (see D.2.3 and D.4.15).
D.4.4ENUMERATED tag numbers start at one, and are allocated sequentially.
D.4.5Anonymous types are not used. Non-trivial fields are assigned their own named type.
D.4.6Consideration is given to making types re-usable and independent of a particular release. Re-using or extending an existing type, where the intent is similar, is preferable to creating a new type.
D.4.7Consideration is given to making types extensible by declaring them as a SEQUENCE or CHOICE where possible.
D.4.8Multiple smaller messages or structures with fewer OPTIONAL fields are preferred to larger structures with many OPTIONAL fields, as this increases the ability of the ASN.1 schema to enforce the intent of the specification.
D.4.9Field names, tag numbers, field types and optional flags are be space-aligned where possible. An indent of four spaces is used.
D.4.10(Void).
D.4.11Braces are given their own line.
D.4.12OIDs containing a version number are updated when the structure that uses the OID is changed, even if the change is solely to correct a syntactic error. Other OIDs in the same module need not be updated if they are not associated with structures that have been changed.
D.4.13For backward compatibility, fields added to existing SEQUENCE or SET are defined as OPTIONAL, irrespective of their M/C/O designation in the main body of the specification.
D.4.14When a field is deprecated, the ASN.1 field is renamed to deprecated{PreviousName} as per the main text (see D.2.5).
D.4.15XIRIEvent and IRIEvent field names are identical for the same field purpose and tag numbers are identical for the same field purpose. If the field is not present in one of XIRIEvent or IRIEvent, a comment reserving the tag is added instead (see D.2.3).
Figure 2 - Syntax convention examples
Figure 3 - Syntax convention counter-examples
Up

D.5  Referencing ASN.1 componentsp. 402

This document utilizes the formal reference notation defined by ITU-T Recommendation X.680 [124] clause 15 to identify specific ASN.1 components. The specific conventions described below only apply to this document. In the event of a conflict between ITU-T Recommendation X.680 [124] and the present document, the terms of the present document shall apply.
ASN.1 references are italicized to aid in their identification.
Relative references may be used but shall only be used when the root of the path is either explicitly defined or may be definitively determined based on the context.
Unless otherwise specified, the root of all references in this document is @TS33128Payloads.
Unless otherwise specified the absolute reference for an xIRI record shall be @TS33128Payloads.XIRIPayload.event.{ComponentID} where the {ComponentID} is the name of the message. When a parameter or type being described is being described in the context of an xIRI message, the absolute reference described above shall be used as the root for any relative references.
Unless otherwise specified the absolute reference for an IRI record shall be @TS33128Payloads.IRIPayload.event.{ComponentID} where the {ComponentID} is the name of the message. When a parameter or type being described is being described in the context of an IRI message, the absolute reference described above shall be used as the root for any relative references.
Up

Up   Top   ToC