Content for TS 33.128 Word version: 18.7.0

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.1 Introduction D.2 Drafting conventions D.3 Naming conventions D.4 ASN.1 Syntax conventions D.5 Referencing ASN.1 components
...

D Drafting Guidance p. 399

D.1 Introduction p. 399

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

D.2 Drafting conventions p. 399

Drafting conventions are described in Table D.2-1.

Table D.2-1: Drafting conventions

ID	Description
D.2.1	The 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.2	The field names used in the main body of the document match those used in the ASN.1.
D.2.3	ASN.1 comments are not used, except to indicate: 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. 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. Where fields in XIRIEvent and IRIEvent for a given NF are continued from a previous disjoint tag number. 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.4	If 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.6	When 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."

D.3 Naming conventions p. 400

ASN.1 naming conventions are described in Table D.3-1, and examples of naming conventions to avoid are shown in Figure 1.

Table D.3-1: Naming conventions

ID	Description
D.3.1	To meet ASN.1 syntax rules, the first character of each ASN.1 field name are lower-cased.
D.3.2	To meet ASN.1 syntax rules, the first character of an ASN.1 type name are upper-cased.
D.3.3	To meet ASN.1 syntax rules, the first character of a field or a type name is not a number.
D.3.4	Only the character ranges A-Z, a-z and 0-9 are used in names.
D.3.5	Names 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.6	Any acronyms in a name are entirely upper-cased (except for the first character of the name - see rule D.3.1).

ExampleBadStructure ::= SEQUENCE
{
 FirstField [1] FirstFieldType, -- D.3.1 First letter of field is upper case
 secondField [2] secondFieldType, -- D.3.2 First letter of type is lower case
 3rdField [3] 3rdFieldType, -- D.3.3 Names starts with digit
 fourth-field [4] Fourth_Field_Type, -- D.3.4 Names include hyphen and underscore
 fifthfield [5] Fifthfieldtype, -- D.3.5 Names are not camelCased
 msisdn [6] MSISDN, -- D.3.6 Acronyms in field name not wholly upper-cased
 mSISDN [7] Msisdn -- D.3.6 Acronyms in type name not wholly upper-cased
}

Figure 1 - Naming convention counter-examples

D.4 ASN.1 Syntax conventions p. 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.

Table D.4-1: ASN.1 Syntax conventions

ID	Description
D.4.1	Modules are be defined with EXTENSIBILITY IMPLIED unless there is a specific reason to limit extensibility.
D.4.2	The AUTOMATIC TAGS module directive is not used.
D.4.3	SEQUENCE 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.4	ENUMERATED tag numbers start at one, and are allocated sequentially.
D.4.5	Anonymous types are not used. Non-trivial fields are assigned their own named type.
D.4.6	Consideration 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.7	Consideration is given to making types extensible by declaring them as a SEQUENCE or CHOICE where possible.
D.4.8	Multiple 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.9	Field 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.11	Braces are given their own line.
D.4.12	OIDs 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.13	For 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.14	When a field is deprecated, the ASN.1 field is renamed to deprecated{PreviousName} as per the main text (see D.2.5).
D.4.15	XIRIEvent 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).

ConformantModule
{itu-t(0) identified-organization(4) etsi(0) securityDomain(2) lawfulIntercept(2) ... }
DEFINITIONS IMPLICIT TAGS EXTENSIBILITY IMPLIED ::=
BEGIN
Structure1 ::= SEQUENCE
{
 field1 [1] Field1,
 field2 [2] Field2
}
Field1 ::= ENUMERATED
{
 choice1(1),
 choice2(2),
 choice3(3)
}
Field2 ::= OCTET STRING
END

Figure 2 - Syntax convention examples

NonconformantModule
{itu-t(0) identified-organization(4) etsi(0) securityDomain(2) lawfulIntercept(2) ... }
DEFINITIONS AUTOMATIC TAGS ::= -- D.4.1 Not declared with EXTENSIBILITY IMPLIED
 -- D.4.2 Declared AUTOMATIC TAGS
BEGIN
Structure1 ::= SEQUENCE { -- D.4.11 Braces not given their own line
 field1 [0] ::= ENUMERATED -- D.4.3 SEQUENCE tags don't start at 1
 { -- D.4.5 Anonymous type used
 choice1(0), -- D.4.4 ENUMERATED tag numbers don't start at 1
 choice2(2),
 choice3(3)
 },
 field2 [2] Field2
}
Field2 ::= OCTET STRING
END

Figure 3 - Syntax convention counter-examples

D.5 Referencing ASN.1 components p. 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.