6 NRM Stage 3 definition rules

32.1603GPPManagement and orchestrationManagement service templateRelease 17TS

Tools: ARFCN - Frequency Conversion for 5G NR/LTE/UMTS/GSM

6.1 Mappings from stage 2 artefacts to stage 3 JSON schema

6.1.1 Usage of JSON schema

JSON schema is used to describe a set of valid schema documents sent over the wire in HTTP request and response messages of the ProvMnS. JSON schema does not describe the concrete implementation of the NRM on the producer.

Definitions are written in YAML.

6.1.2 Concrete NRM classes

A NRM class (managed object class) is represented by a JSON object. The properties of the JSON object are the NRM class attributes and the name contained NRM classes.

YAML schema

YAML document example

type: object

properties: {}

{}

In the following example the class contains an "attributeA" of type "string" and an "attributeB" of type "number".

YAML schema

YAML document example

type: object

properties:

attributeA:

type: string

attributeB:

type: number

attributeA: ABC

attributeB: 45

The JSON object representing the class instance is preceded by a key equal to the class name.

In the following example the class name is "classA". Attributes are omitted for the sake of simplicity.

YAML schema

YAML document example

type: object

properties:

classA:

type: object

properties: {}

classA: {}

Multiple managed object instances of the same class are represented using a JSON array, where each item of the array is a JSON object with a managed object class instance representation.

YAML schema

YAML document example

type: object

properties:

ClassA:

type: array

items:

type: object

properties: {}

ClassA:

– {}

6.1.3 Abstract classes

Abstract classes shall be defined in a "definitions" object and referenced in the schema of the concrete class using the "$ref" keyword.

In the following example the abstract class can be instantiated zero or one time..

YAML schema

YAML document example

definitions:

ClassA-Abstract:

type: object

properties: {}

type: object

properties:

ClassA:

$ref: ‘#/definitions/ClassA-Abstract’

ClassA: {}

In the following example the abstract class can be instantiated zero or more times.

YAML schema

YAML document example

definitions:

ClassA-Abstract:

type: object

properties: {}

type: object

properties:

ClassA:

type: array

items:

$ref: ‘#/definitions/ClassA-Abstract’

ClassA:

– {}

Abstract classes can be defined as well in separate files. Assume a file with the name "myDefs.json" includes the "definitions" object with the definition of "ClassA-Abstract ".

YAML schema

YAML document example

definitions:

ClassA-Abstract:

type: object

properties: {}

The definition of "ClassA-Abstract" is then referenced like

YAML schema

YAML document example

type: object

properties:

ClassA:

type: array

items:

$ref: ‘myDefs.json#/definitions/ClassA-Abstract’

ClassA:

– {}

6.1.4 Name containment

Name contained NRM class instances are modeled as property of the containing class. The name of the property is the class name. The value is an array with manged object class representations of that class. Cardinality of the name containment relationship is specified using the "minItems" and "maxItems" keywords.

If the maximum number of items is unbounded, the "maxItems" keyword shall be omitted. If the minimum number of items is 0, the "minItems" keyword can be omitted.

The contained class shall not be listed as required property. This allows omitting the property representing the contained class instances completely in a JSON document instead of having an empty array.

In the following example an instance of "classA" name contains 1…1000 instances of "classB".

YAML schema

YAML document example

type: object

properties:

ClassA:

type: array

items:

type: object

properties:

ClassB:

type: array

minItems: 1

maxItems: 1000

items:

type: object

properties: {}

ClassA:

– ClassB:

– {}

Managed objects class instances of more than one class can be name contained.

YAML schema

YAML document example

type: object

properties:

ClassA:

type: array

items:

type: object

properties:

ClassB:

type: array

items:

type: object

properties: {}

ClassC:

type: array

items:

type: object

properties: {}

ClassA:

– ClassB:

– {}

– ClassC:

– {}

The contained managed object classes may be defined as abstract classes first, and then referenced.

YAML schema

YAML document example

definitions:

ClassB-SingleAbstract:

type: object

properties: {}

ClassC-SingleAbstract:

type: object

properties: {}

type: object

properties:

ClassA:

type: array

items:

type: object

properties:

ClassB:

type: array

items:

$ref: ‘#/definitions/ClassB-SingleAbstract’

ClassC:

type: array

items:

$ref: ‘#/definitions/ClassC-SingleAbstract’

ClassA:

– ClassB:

– {}

– ClassC:

– {}

or, when the abstract class is defined as an array, then

YAML schema

YAML document example

definitions:

ClassB-MultipleAbstract:

type: array

items:

type: object

properties: {}

ClassC-MultipleAbstract:

type: array

items:

type: object

properties: {}

type: object

properties:

ClassA:

type: array

items:

type: object

properties:

ClassB:

$ref: ‘#/definitions/ClassB-MultipleAbstract’

ClassC:

$ref: ‘#/definitions/ClassC-MultipleAbstract’

ClassA:

– ClassB:

– {}

– ClassC:

– {}

6.1.5 Recursive name containment

Classes may name contain themselves. This shall be modeled in JSON schema with recursion. Recursion requires using a "definitions" object with the definition of an abstract class.

In the following example each instance of "classA" contains zero or one instance of "classA".

YAML schema

YAML document example

definitions:

ClassA-Abstract:

type: object

properties:

classA:

$ref: ‘#/definitions/ClassA-Abstract’

type: object

properties:

ClassA:

$ref: ‘#/definitions/ClassA-Abstract’

ClassA:

ClassA: {}

In the following example each instance of "classA" contains zero or more instances of "classA".

YAML schema

YAML document example

definitions:

ClassA-MultipleAbstract:

type: array

items:

type: object

properties:

classA:

$ref: ‘#/definitions/ClassA-MultipleAbstract’

type: object

properties:

ClassA:

$ref: ‘#/definitions/ClassA-MultipleAbstract’

ClassA:

– ClassA:

– {}

– ClassA:

– {}

6.1.6 Inheritance

JSON schema does not have the concept of inheritance. Inheritance can be emulated by the composition of schemas with the "allOf" keyword.

In the following example the attribute "attrB" is added to the attribute "attrA" of "classA-Abstract" to construct "ClassB".

YAML schema

YAML document example

definitions:

ClassA-Abstract:

type: object

properties:

attrA:

type: string

type: object

properties:

ClassB:

type: array

items:

allOf:

– $ref: ‘#/definitions/ClassA-Abstract’

– type: object

properties:

attrB:

type: number

ClassB:

– attrA: ABC

attrB: 5

– attrA: DEF

attrB: 4

– attrA: GHI

attrB: 23

The other possibility is to specify the inherited attribute directly along with the added attributes, thus having no inheritenace or any emulation thereof in NRM stage 3 definitions.

6.1.7 NRM class naming attribute "id"

The naming attribute "id" is mapped to a required property of the class object, where the key is "id" and the type is "string".

YAML schema

YAML document example

type: object

properties:

ClassA:

type: array

items:

type: object

properties:

id:

type: string

required:

– id

ClassA:

– id: ‘1’

– id: ‘2’

– id: ‘3’

6.1.8 NRM class attributes

NRM class attributes other than the naming attribute "id" shall be carried as properties in an "attributes" object.

YAML schema

YAML document example

type: object

properties:

classA:

type: array

items:

type: object

properties:

id:

type: string

attributes:

type: object

properties: {}

required:

– id

classA:

– id: ‘1’

attributes: {}

– id: ‘2’

attributes: {}

– id: ‘3’

attributes: {}

The class attributes are name/value pairs (properties) of the "attributes" object.

6.1.9 Vendor specific extensions

Vendor-specific attributes shall be added to standardized JSON schemas using the mechanism in clause 6.1.6 "Inheritance".

6.1.10 Attribute support qualifier

The attribute support qualifier is defined in clause 6 of TS 32.156 [3]. This qualifier specifies a requirement for the MnS producer.

Attributes may or may not be present in a JSON document carried in a HTTP request or response message, no matter what their support qualifier in the NRM is. For this reason, no qualification is required for attributes in the JSON schema for NRMs. By default, the properties defined by the "properties" keyword are not required and can be omitted in a document instance.

However, some attributes like the "id" naming attribute shall be always present when a managed object class instance is carried in a HTTP request or response. These attributes shall be listed as array items in the value of the "required" keyword.

YAML schema

YAML document example

type: object

properties:

classA:

type: array

items:

type: object

properties:

id:

type: string

required:

– id

classA:

– id: ‘1’

– id: ‘2’

– id: ‘3’

6.1.11 Attribute properties

6.1.11.1 Introduction

The attribute properties are defined in clause 5.2.1.1 of TS 32.156 [3]. They reflect properties of the attributes exhibited by the MnS producer. Their purpose is not to specify requirements for the attribute when transferred over the wire. For this reason, care should be taken when mapping attribute properties to JSON schema keywords.

6.1.11.2 Attribute property "multiplicity"

Attributes of scalar type with multiplicity equal to "1" are mapped to a name/value pair whose value is either a number, a string or one of the literal names false, null or true.

Attributes of scalar type with nultiplicity bigger than "1" are mapped to a name/value pair whose value is a JSON array, and the array items are either a number, a string or one of the literal names false, null or true.

Attributes of structured type with multiplicity equal to "1" are mapped to a single name/value pair whose value is a JSON object, whose properties are described by the structured data type.

Attributes of structured type with multiplicity greater than "1" are mapped to a name/value pair whose value is a JSON array, and the items are JSON objects, whose properties are described by the structured data type.

6.1.11.3 Attribute property "isUnique"

The semantics of his attribute property is mapped to the "uniqueItems" keyword with a value set to true.

properties:

flower:

type: array

uniqueItems: true

items:

type: string

6.1.11.4 Attribute property "isOrdered"

This attribute property is a requirement for the MnS producer and not mapped to any JSON schema keyword.

6.1.11.5 Attribute property "defaultValue"

This attribute property is a requirement for the MnS producer and not mapped to any JSON schema keyword.

Note: The OpenApi Specification [14] defines the "default" keyword. This default value represents what would be assumed by the consumer of the input as the value of the schema if a value is not provided in the consumed JSON instance document. The sematics of default in the OpenApi Specification [14] is hence different from the semantics of default in TS 32.156 [3].

6.1.11.6 Attribute property "isNullable"

The semantics of this attribute property is mapped to the "nullable" keyword with a value set to true.

Example:

properties:

flower:

type: string

nullable: true

Note: The "nullable" keyword is defined only in the OpenApi Specification [14]. JSON schema as defined in [15], [16], [17] does not specify this keyword.

6.1.11.7 Attribute property "isInvariant"

This attribute property is a requirement for the MnS producer and not mapped to any JSON schema keyword.

6.1.11.8 Attribute property "isReadable" and "isWritable"

The semantics of these properties are mapped to the "readOnly" and "writeOnly" keywords with the values set according to the following table. The default value of the "readOnly" and "writeOnly" keywords is boolean "false".

Stage 2 statement

Stage 2 semantic

Stage 3 statements

Stage 3 semantic

isReadable=True (default)

isWritable=True (default)

Attribute can be read.

Attribute can be written.

readOnly=False (default)

writeOnly=False (default)

Attribute can be read.

Attribute can be written.

isReadable=True (default) isWritable=False

Attribute can be read.

Attribute cannot be written.

readOnly=True

writeOnly=False (default)

Attribute can be read.

Attribute cannot be written.

isReadable=False isWritable=True (default)

Attribute cannot be read.

Attribute can be written.

readOnly=False (default)

writeOnly=True

Attribute cannot be read.

Attribute can be written.

isReadable=False isWritable=False

Attribute cannot be read.

Attribute cannot be written.

readOnly=True

writeOnly=True

Attribute cannot be read.

Attribute cannot be written.

If "writeOnly" for an attribute has a value of boolean "true", it indicates that the attribute shall never be present in instance documents sent by the MnS producer to the MnS consumer.

If "readOnly" for an attribute has a value of boolean "true", it indicates that the attribute shall never be present in instance documents sent by the the MnS consumer to the MnS producer.

Example:

properties:

flower:

type: string

readOnly: true

writeOnly: false

6.1.11.9 Attribute property "isNotifyable"

This attribute property is a requirement for the MnS producer and not mapped to any JSON schema keyword.

6.1.11.10 Attribute property "allowedValues"

Allowed values for "string" are specified using the "minLength", "maxLength" and "pattern" keywords.

Allowed values for "number" and "integer" are specified using the "multipleOf", "maximum", "exclusiveMaximum", "minimum" and "exclusiveMinimum" keywords.

Allowed values of any type can be restricted by using the "enum" and "const" keywords.

6.2 Stage 3 YANG style and example

The next clause defines general rules for YANG modules. The following clauses specify how specific Stage to constructs should be mapped to YANG. Each clause may include the following clauses:

– The clause of Reference [3] for which mapping is specified.

– An example model that will be mapped.

– Mapping rules.

– An example of the resulting YANG statements.

6.2.1 General Modeling Rules

6.2.1.1 Modeling Resources

Resources shall be modeled as YANG data nodes (leaf, leaf-list, container, list) instead of Classes and Attributes. Specific operations shall be modelled as YANG actions.

6.2.1.2 Unique YANG Module names

The names of 3GPP YANG modules shall start with the "_3gpp" prefix.

6.2.1.3 Unique YANG Namespace

The namespace of a 3GPP YANG module’s namespace shall have the following form:

urn:3gpp:saX:<module-name>

saX denotes the group creating the relevant YANG model e.g. "sa5"

Reference: https://tools.ietf.org/html/rfc8407#section-4.9 [11].

6.2.1.4 Unique YANG Module Prefixes

3GPP YANG Modules shall use prefixes ending with "3gpp". Prefixes should be short preferably not longer than 10 characters but 13 characters at most.

e.g. prefix nrmtype -> prefix nrmtype3gpp

Note: To ensure that the prefix (in the yang prefix statement) is globally unique a prefix-suffix is used. While global uniqueness of prefixes is not mandatory most SW implementations have problems and need workarounds in case conflicting prefixes are found.

6.2.1.5 Use YANG Version 1.1

YANG version 1.1 shall be used.

6.2.1.6 YANG Constructs Not to be Used – Not needed

The following YANG constructs shall not be used in 3GPP YANG models as they are not available in the Stage 2 modeling terminology, thus not needed.

– Anydata

– AnyXml

– Rpc – use actions instead

– Deviation

6.2.1.7 Reuse Standards from Other Standard Organizations

Whenever there is a suitable existing standard from another standard organization or industry forum its usage should be preferred before defining a 3GPP model covering the same scope. E.g. ietf-types, ietf-inet-types

3GPP models shall link to and reference YANG models from other standard organizations/industry forum whenever applicable.

6.2.1.8 Vendor Specific Model Changes

Vendors shall not modify 3GPP YANG modules either by changing the original file or by adding vendor specific YANG modules that contain deviations targeting parts of a 3GPP module. Only the following exceptions are allowed from the above rule:

– Deviations that maintain backwards compatibility as defined in RFC 7950 [18] are allowed

– Marking as "not supported" any model element that is optional to support as defined by the 3GPP stage 2 supportQualifier is allowed.

Vendors extensions shall be done in separate YANG modules; they do not impact compliance.

6.2.1.9 Model Correctness, checking

3GPP YANG modules shall be checked with the pyang tool. See: PYANG an extensible YANG validator and converter

The "pyang –-strict" command shall be run with no errors returned.

"pyang —lint" should also be run against all 3GPP YANG modules. Errors and warning produced by the "pyang –lint" checks should be removed. However, as these errors/warnings do not affect the corretness or functionality of the YANG module, and in some cases the changes needed to remove them would actually degrade readability, it is not a required to remove the errors/warnings produced by the "pyang –lint".

6.2.1.10 YANG modules in technical specifications

If a module’s text is included in a technical specification, each YANG module shall be contained in a separate clause. The clause’s title shall not include the revision date of the module.

To facilitate automatic code extraction from the MS Word specification:

– Immediately before the first line of a YANG module/submodule a line should be inserted containing only the text

– the module’s first statement shall start with the keyword "module" (or submodule) in the first place (no whitespace allowed before it on the line).

– followed by a single space.

– followed by the name of the module/submodule.

– followed by a single space and an opening curly bracket "{".

– All following lines shall be indented at least with two spaces.

– the last line of the module shall be a single “}” without any characters before or after it (especially no white space before it)

– Immediately after the last line of a YANG module/submodule a line should be inserted containing only the text

6.2.1.11 Module header statements

A module’s organization and description statements shall be present. The organization shall include the string "3GPP".

A module shall contain the following contact statement:

contact "https://www.3gpp.org/DynaReport/TSG-WG–S5–officials.htm?Itemid=464;"

6.2.1.12 Provide description and reference statements

A "description" statement should be present for each YANG schema node. As an exception: for individual leafs, leaf-lists, enums, case statements, typedef statements, where the schema node’s name describes the node sufficiently, the "description" may be omitted.

A "reference"substatement to the module statement shall be present that specifies the technical specification where the YANG module is defined. In order to easily list with a “grep” command YANG modules belonging to a specific technical specification, the format of the first line of this reference statement shall start exactly with:

– new-line followed by

– the string ‘ reference ”3GPP TS ‘

(that is 2 leading spaces + reference + 1 space + a double quote + 3GPP TS + 1 more space) followed by

– the number of the technical specification.

E.g." reference "3GPP TS 28.622".

6.2.1.13 YANG module revisions

A separate "revision" statement shall be present for each published version of a module. The revision statement shall contain a reference substatement listing the numbers of all 3GPP change requests and any other documents that resulted in the creation of the new revision.

Example:

revision 1956-10-13 {

reference “CR-0258, CR-0267”;}

NOTE: Void.

If multiple change requests modify the new revision of a YANG module, the content of the reference substatements should be merged.

6.2.1.15 Don’t use YANG statements with their default meaning

YANG statements config, mandatory, max-elements, min-elements, ordered-by, status, yin-element have a specific meaning even if they are absent. The default meaning for these statements should not be explicitly declared in a YANG Module.

E.g. if the mandatory statement is missing that is equivalent to the situation where "mandatory false" is specified; it does not change the meaning of the YANG module, it just makes it longer.

6.2.1.16 Formatting YANG modules/submodules

YANG modules are part of the end-user documentation so to enhance readability the following guidelines should be followed. The guidelines are important as YANG files are often compared and processed as simple text files by SW tools.

– YANG modules should not contain lines longer then 80 characters. (YANG files are often read by the end-users as-is, and reading files with long lines is problematic.)

– A line in a YANG should not contain whitespace (space, tab) immediately before the end of a line or at the end of the file after the last non-blank line. Additional whitespace will confuse tooling when comparing different versions of the YAM.

– Instead of tabs consecutive spaces (a.k.a. soft-tabs) should be used. As different editors use different length tabs (2,4,8 characters long) the indentation of the module might become messed up. Using mixed indentation (both hard-tabs and spaces) is especially problematic.

– In order to avoid long lines the normal indentation should be 2 spaces.

– YANG files should not use characters outside the US-ASCII character set unless there is a specific need for it.

– End-of-line separator SHALL use only a single Newline without a Carriage-Return character.

6.2.1.17 Use original prefix under import statements

The prefix substatement under an import statement shall use the same prefix value, that the imported module declared in it’s prefix substatement under it’s module statement.

6.2.1.18 YANG Naming

All YANG schema nodes and identifiers that are a direct mapping from the stage 2 specifications (including leafs, leaf-list, containers, lists, enumerations, enums, typedefs) shall have the exact same name as used in stage 2 definitions except if

– stage 2 name violates the allowed naming rules of the YANG language as defined in RFC7950 [18] section 6.2.

– Specified otherwise in the present document.

6.2.2 InformationObjectClass – abstract

6.2.2.1 Introduction

Reference [3] clause 5.4.2

6.2.2.2 YANG mapping

An abstract class shall be mapped to a "grouping". The name of the "grouping" will be <IocName>Grp. The "grouping" shall contain all attributes of the class. The naming attribute shall only be contained as a YANG comment, because all other attributes will be contained in a YANG "non-presence container" named "attributes", however the "key leaf" is contained immediately by the "list", it cannot be inside a child "container".

// abstract class MyClass_

grouping MyClass_Grp {

// contains all contained attributes

// the leaf of the namingAttribute is either not included or

// included only as a comment not as a real definition

// leaf id {

// type string;

// description "naming attribute of the IOC";

// }

leaf attribute1 {..}

leaf-list attribute2 {..}

}

6.2.3 Naming attribute

6.2.3.1 Introduction

Reference [3] clause 3.1

6.2.3.2 Yang mapping

The "leaf" that is mapped from the naming attribute shall be used in the YANG "key" statement. This is usually called "id" as defined in the Top_ class in TS 28.620 Umbrella Information Model (UIM), clause 4.3.8.

6.2.4 InformationObjectClass – concrete

6.2.4.0 Introduction

Reference [3] clause 5.3.2

6.2.4.1 YANG mapping

A concrete class shall be mapped to a "list" that "uses" a "grouping". The "grouping" shall be named <IocName>Grp. It shall contain all attributes of the class in the same manner as the "grouping" for an abstract class. The "list" shall be named <IocName>. The NamingAttribute shall be used as a key. All other attributes shall be placed inside a "container" named "attributes". The "container attributes" will facilitate asking for all attributes of an object instance with a simple subtree or XPath filter.

//concrete class

grouping MyConcreteClassGrp {

// contains all attributes in the same manner as

// a grouping for abstract class

}

list MyConcreteClass {

key namingAttribute; // usually named ‘id’

leaf namingAttribute {…}

container attributes {

uses MyConcreteClassGrp ;

}

//YANG lists representing contained classes

}

6.2.5 Generalization relationship – inheritance from another class

6.2.5.1 Introduction

Reference [3] clause 5.2.5

Example model: Class MyManagedFunction inherits from class ManagedFunction.

6.2.5.2 YANG mapping

Generalization/Inheritance relationships are mapped to the inheriting class using the "grouping" of the inherited class in its own "grouping".

// Inheritance

grouping ManagedFunctionGrp {

// Attributes of ManagedFunction

}

grouping MyManagedFunctionGrp {

uses ManagedFunctionGrp;

//additional attributes

}

list MyManagedFunction {

key id;

leaf id {}

container attributes {

uses MyManagedFunctionGrp;

}

6.2.6 Name containment

6.2.6.1 Introduction

Reference [3] clause 5.2.4 – Composite aggregation association relationship

Example model: The classes ParentClass and LocalChildClass are defined in the YANG module _3gpp-ParentClass. ParentClass name-contains LocalChildClass. Another YANG module (_3gpp-ChildClass) defines classes ChildClass1 and ChildClass2. ParentClass name-contains ChildClass1 and ChildClass2.

As on Stage 2 all name-containment is optional, an if-feature statement should be added under “list”, “uses” or “augment” statements modeling name-containment. However, if a YANG module models only a single containment relationship, which is modeled by an augment statement, the if-feature statement is not needed, as the optionality is modeled with the implementation or the non-implementation of the module.

The YANG feature should be named <Child>Under<ParentIocName> . The <Child> section is usually not the name of a specific class, but some name identifying a collection of child classes. The feature statement should be placed in the YANG module where it is used.

Even if a containment relationship (and the contained IOC) is marked as not supported by the YANG feature, any imported but not implemented YANG modules still need to be present in the product with a conformance statement import-only. (See RFC 7895 leaf conformance-type). This should not be a problem for implementers as real implementation is not needed, only the YANG files need to be present.

6.2.6.2 YANG mapping

6.2.6.2.1 General

The containment of classes defined in the same YANG module is mapped as embedded "lists".

Containment of classes defined in different YANG modules can be mapped in one of two ways.

6.2.6.2.2 Simple augment

Containment is mapped using the "augment" statement. This is the preferred method.

// Class containment

module _3gpp-ParentClass {

feature LocalChildClassUnderParentClass {

description “Indicates that LocalChildClass is contained under ParentClass”;

}

grouping LocalChildClassGrp {

// LocalChildClass attributes

}

grouping ParentClassGrp {

// ParentClass attributes

}

list ParentClass {

key id;

leaf id {}

attributes {

use ParentClassGrp;

}

list LocalChildClass {

if-feature LocalChildClassUnderParentClass ;

key id;

leaf id {}

attributes {

uses LocalChildClassGrp;

}

// place to insert/augment child classes

}

module _3gpp-ChildClass {

import _3gpp-ParentClass { prefix xx3gpp;}

feature ChildClass1UnderParentClass {

description “Indicates that ChildClass1 is contained under

ParentClass”;

}

feature ChildClass2UnderParentClass {

description “Indicates that ChildClass2 is contained under

ParentClass”;

}

grouping ChildClass1Grp {

// ChildClass1Grp attributes

}

grouping ChildClass2Grp {

// ChildClass2Grp attribute

}

augment /xx3gpp:ParentClass {

if-feature ChildClass1UnderParentClass;

list ChildClass1 {

key id;

leaf id {}

attributes {

uses ChildClass1Grp;

}

augment /xx3gpp:ParentClass {

if-feature ChildClass2UnderParentClass;

list ChildClass2 {

key id;

leaf id {}

attributes {

uses ChildClass2Grp;

}

6.2.6.2.3 Uses + Subtree grouping

Containment is mapped using the "uses" statement towards a subtree grouping that contains the lists representing the child IOCs; e.g. ParentClass contains ChildClass1 and ChildClass2. This method is recommended when a group of multiple classes is contained together in a number of other classes. In this case optionality is handled on the common subtree level. (The subtree may actually be a group of classes or multiple trees.)

// Class containment

module _3gpp-ParentClass {

import _3gpp-ChildClass { prefix yyy3gpp; }

feature CommonUnderParentClass {

description "Indicates that the CommonSubtree shall be contained

under ParentClass";

}

feature LocalChildClassUnderParentClass {

description “Indicates that LocalChildClass is contained under

ParentClass”;

}

grouping LocalChildClassGrp {

// LocalChildClass attributes

}

grouping ParentClassGrp {

// ParentClass attributes

}

list ParentClass {

key id;

leaf id {}

attributes {

use ParentClassGrp;

}

list LocalChildClass {

if-feature LocalChildClassUnderParentClass ;

key id;

leaf id {}

attributes {

uses LocalChildClassGrp;

}

uses yyy3gpp:CommonSubtree {

if-feature CommonUnderParentClass ;

}

module _3gpp-ChildClass {

grouping ChildClass1Grp {

// ChildClass1Grp attributes

}

grouping ChildClass2Grp {

// ChildClass2Grp attributes

}

grouping CommonSubtree {

list ChildClass1 {

key id;

leaf id {}

attributes {

uses ChildClass1Grp;

}

list ChildClass2 {

key id;

leaf id {}

attributes {

uses ChildClass2Grp;

}

6.2.7 Recursive containment – reference based solution

The NRM information object class stage 2 definition contains one case where a class contains itself (so called recursive containment): the It is the SubNetwork class.

The name containment that a class has with itself in the stage 2 definition shall be modeled using a pair of "leaf-list" references between the instances of the class. The references shall be named "leaf-list parents {…}" and "leaf-list containedChildren {…}". Note the 2 reference "leaf-lists" should be defined directly under the "list" defining the class not in its "grouping" because the "path" statements are specific to each class, so the "leaf-lists" must not be inherited.

list SubNetwork {

key id;

leaf id {..}

container attributes {

uses SubNetworkGrp;

leaf-list parents {

description "Reference to all containg SubNetwork instances

in strict order from the root subnetwork down to the immediate

parent subnetwork.

If subnetworks form a containment hierarchy this is

modeled using references between the child SubNetwork and the parent

SubNetworks.

This reference MUST NOT be present for the top level SubNetwork and

MUST be present for other SubNetworks.";

type leafref {

path "../../../SubNetwork/id";

}

leaf-list containedChildren{

description "Reference to all directly contained SubNetwork instances.

If subnetworks form a containment hierarchy this is

modeled using references between the child SubNetwork and the parent

SubNetwork.";

type leafref {

path "../../../SubNetwork/id";

}

The following instance data example shows how the reference values specify the SubNetwork hierarchy:

Top level: subnet=root

| \ +—————-+

| +——–+ |

| | |

Level 1: subnet=A1 subnet=B1 subnet=C1

| \ +—————-+

| +——–+ |

| | |

Level 2: subnet=A2 subnet=B2 subnet=C2

| \ +—————-+

| +——–+ |

| | |

Level 3: subnet=A3 subnet=B3 subnet=C3

Top level: id=root parents=null containedChildren= A1,B1,C1

Level 1: id=A1,(B1,C1) parents=root containedChildren = A2,B2,C2

Level 2: id=A2,(B2,C2) parents=root,A1 containedChildren = A3,B3,C3

Level 3: id=A3,(B3,C3) parents=root,A1,A2 containedChildren = A4,B4

When reading/writing self-contained classes only the last such class instance needs to be specified in the Netconf request as that uniquely identifies the exact instance. The following Netconf request could be used to retrieve all attributes of SubNetwork=root, SubNetwork=A1, SubNetwork=B2, NRFrequency=22

<get-config>

</source>

<!– SubNetwork=root, SubNetwork=A1, SubNetwork=B2, NRFrequency=22 –>

</NRFrequency>

</SubNetwork>

</get-config>

</rpc>

There is no need to specify the ancestors SubNetwork=root, SubNetwork=A1 as any subNetwork can be addressed directly.

6.2.8 Multi-root management tree

YANG supports multi-rooted managed models natively; the standardized IETF models have many root "list"/"container" nodes.

6.2.9 Alternative containment

Stage 2 models allows multiple different name-containment hierarchies. A particular name-containment hierarchy implemented by a specific vendor/product can be discovered in run-time, by reading the content of the ietf-yang-library and the ietf-yang-schema mount modules.

YANG provides multiple possible methods to model alternative containment hierarchies.

In cases where the number of YANG modules affected by the alternative containment is small, the use of a feature-controlled augmentation is proposed.

augment "/SubNetwork" {

if-feature ExternalsUnderSubNetwork ;

uses ExternalNRCellCUWrapper;

}

In cases where the number of YANG modules affected by the alternative containment is large (cca. more than 8), the following mapping is proposed (using the optional containment of SubNetwork and ManagedElement as an example):

– If the ManagedElement is a root class, no further documentation or implementation steps are required.

– If the ManagedElement shall be contained under Subnetwork it shall be mounted under the SubNetwork "list" using the YANG schema mount mechanism as described in RFC8528.[13]

Mounted schemas will appear in Netconf, the CLI and management GUIs as if they were part of a common containment hierarchy.

Yang Schema Mount provides vendor the flexibility of arranging the containment tree in accordance of operator intention, and provides a way for a consumer to discover the actual mount and containment hierarchy in run-time.

6.2.10 Attribute – simple, single value

6.2.10.1 Introduction

Reference TS 32.156 [3] clause 5.2.1

The multiplicity of the attribute is either 0..1 or 1..1.

6.2.10.2 YANG Mapping

Non-structured single value attributes are mapped to a "leaf".

// attribute single value, nonstructured

leaf myAttribute { type xxx; }

6.2.11 Attribute – simple, multivalue

6.2.11.1 Introduction

Reference [3] clause 5.2.1

The multiplicity of the attribute may be greater than 1.

6.2.11.2 YANG mapping

If the attribute is isUnique=true it shall be mapped mapped to a leaf-list.

If the attribute is isUnique=false it shall be mapped to a list with an additional dummy index. The name of the list shall be <attributeName>Wrap. The name of the dummyIndex shall be idx and shall have a type uint32 or uint64.

// Attribute multivalue, non-structured

// attribute is unique

leaf-list mySimpleMultivalueAttribute1 { type xxx; }

// attribute is non-unique

list mySimpleMultivalueAttribute2Wrap {

key idx;

leaf idx { type uint32 ; }

leaf mySimpleMultivalueAttribute2 {type xxx;}

6.2.12 Attribute, structured

6.2.12.0 Introduction

Reference TS 32.156 [3] clause 5.2.1

6.2.12.1 YANG Mapping

Structured attributes are mapped to a grouping containing member parts; and a list using the grouping. (Structured attributes that are not used in multiple places may define the member parts directly in the list.)

// attribute, structured, isUnique=true

grouping pLMNIdGrp {

description "PLMN-Id= Mobile Country Codes (MCC) &

Mobile Network Codes(MNC)";

leaf MCC {

type t_mcc;

}

leaf MNC {

type t_mnc;

}

list pLMNIdList {

key "MCC MNC";

config true;

description "a list of PLMN-Ids";

ordered-by user;

uses pLMNIdGrp;

}

// attribute, structured, isUnique=false

list pLMNIdList {

key "idx";

leaf idx { type uint32 ; };

leaf member1 { type xxx ; }

leaf member2 { type yyy ; }

}

YANG keys for the list shall be selected according to the following steps:

1) If the attribute is isUnique=true and according to the descriptions of the sub-attributes, one or a combination of some subattributes are unique, and all these subattributes are mandatory, these subattribute(s) should be used as key(s) in YANG. (Note only mandatory subattributes should be considered for keys as declaring a subattribute a key makes it mandatory in YANG.)

2) If suitable key(s) cannot be found in step 1, an additional dummy index shall be defined in YANG. The name of the dummyIndex shall be “idx” and shall have a type uint32 or uint64. The dummy key "idx" usually does not appear on stage 2.

6.2.13 defaultValue

6.2.13.1 Introduction

Reference TS 32.156 [3] clause 5.2.1.1.

The 3GPP/UML defaultValue has a different meaning then the YANG "default" statement.

The 3GPP defaultValue could be considered an initialValue as it has effect only at object creation. If the attribute is later deleted the 3GPP defaultValue has no effect. In YANG the "default" is always used whenever a leaf/leaf-list does not have a value: both at creation of the parent object and if the leaf/leaf-list is deleted (set to null in 3GPP operation).

Note: Void

The 3GPP defaultValue, isNullable and multiplicity properties cannot be mapped one-to-one into YANG statements. A combination of these three stage 2 input properties shall result in a combination of the four YANG statements mandatory, min-elements, default,and yext3gpp:initial-value (defined in the YANG module _3gpp-common-yang-extensions.yang). The table below describes the combinations of input properties and the resulting YANG statements.

Stage 2 properties			YANG mapping
multiplicity	isNullable	Stage-2 default	Yang mandatory	YANG Min-Elements > 0	YANG default	YANG initial-value
0..1	True	none	N	N	N	N
	True	defined	N	N	N	Y
	False	none	N	N	N	N
	False	defined	N	N	N	Y
1	True	none	N	N	N	N
	True	defined	N	N	N	Y
	False	none	Y/N	Y/N	N	N
	False	defined	N	N	Y	N
0..*	True	none	N	N	N	N
	True	defined	N	N	N	Y
	False	none	N	N	N	N
	False	defined	N	N	N	Y
x..* x >= 1	True	none	N	N	N	N
	True	defined	N	N	N	Y
	False	none	N	Y	N	N
	False	defined	N	N	Y	N

YANG mandatory indicates that the leaf shall have a “mandatory true;” substatement.

YANG min-elements > 0 indicates that the list or leaf-list shall have a “min-elements” substatement that has an argument that is greater than zero.

YANG default indicates that the leaf shall have a “default” substatement.

YANG initial-value indicates that the leaf should have a “yext3gpp:initial-value” substatement.

6.2.13.2 YANG mapping

YANG "default" and "initial-value" statements are only used for simple attributes. For structured attributes describe the default in the YANG description. In some cases, the stage 2 default value is not defined as a specific value, but rather as a reference or defined in a human readable language. In these cases, the default value is described in the YANG description.

YANG default or yext3gpp:initial-value statements shall be used as specified in the table in clause 6.2.13.1.

Note 1: Void

Note 2: The YANG extension statement yext3gpp:initial-value is not understood or enforced by standard YANG tools, it needs extra SW implementation.

6.2.14 multiplicity and cardinality

6.2.14.0 Introduction

Reference TS 32.156 [3] clause 5.2.1.1

Reference TS 32.156 [3] clause 5.2.8

6.2.14.1 YANG mapping

YANG mandatory, or min-elements statements shall be used as specified in the table in clause 6.2.13.1.

Multiplicity of attributes mapped to a list or leaf-list shall be mapped to the "min-elements" and "max-elements" YANG statements.

Cardinality for containment of classes shall be mapped to "min-elements" and "max-elements" on the list representing the child objects.

Cardinality for reference relationships shall be mapped to "mandatory", "min-elements" and "max-elements" on the reference attributes representing the reference.

6.2.15 isNullable

6.2.15.0 Introduction

Reference TS 32.156 [3] clause 5.2.1.1

6.2.15.1 YANG mapping

isNullable=false for attributes is not mapped to YANG. In this case the attribute’s multiplicity will dictate any YANG mandatory or min-elements statements. See table in clause 6.2.13.1.

isNullable=true shall not be mapped to YANG, because isNullable=true makes the attribute optional to use, which is the default case in YANG, thus it should not be explicitly stated.

A special case is an attribute that is mapped to a list or leaf-lists, is isNullable=true and has a minimum multiplicity greater than zero. In this case a "must" statement shall be added to the list/leaf-list forbidding any multiplicity values between 1 and the minimum multiplicity (but allowing zero and the minimum). See example below:

list nullableListWithMinimumMultiplicityOf5 {

key idx;

must ‘count(.) = 0 or count(.) >= 5’;

leaf idx { type uint32 ; }

leaf nonUniqueSingleValueAttribute [ type int32; };

Note: Void

6.2.16 dataType

6.2.16.0 Introduction

Reference TS 32.156 [3] clause 5.3.4

Reference TS 32.156 [3] clause 5.4.3

6.2.16.1 YANG mapping

Mapping for predefined datatypes shall be the following:

– integer -> One of the 8 YANG integer types

– string – > string

– Boolean -> Boolean

3GPP user-defined simple datatypes shall be mapped to the YANG "typedef" statement.

3GPP user-defined structured datatypes shall be mapped to the YANG "grouping" statement with the name <typeName>Grp.

6.2.17 enumeration

6.2.17.0 Introduction

Reference TS 32.156 [3] clause 5.3.5

6.2.17.1 YANG mapping

The 3GPP enumeration datatype shall be mapped to the YANG "enumeration" YANG type.

6.2.18 choice

6.2.18.0 Introduction

Reference TS 32.156 [3] clause 5.3.6

6.2.18.1 YANG mapping

The 3GPP choice stereotype shall be mapped to a Yang "choice" statement.

6.2.19 isInvariant on attribute

Reference [Error: Reference source not found] clause 5.2.1.1

6.2.19.1 YANG mapping

Attributes with the property isWritable=false shall be mapped to YANG "config false;" leafs/leaf-lists/lists. Config=false nodes are controlled by the system. The user cannot change them at all; isInvariant=true is implied.

Attributes with the properties isWritable=true AND isInvariant=false shall be mapped to YANG "config true;" leafs/leaf-lists/lists.

Attributes with the properties isWritable=true AND isInvariant=true shall be mapped to YANG "config true;" leafs/leaf-lists/lists marked with the "yext3gpp:isInvariant" extension defined in the YANG module _3gpp-common-yang-extensions.yang in 3GPP TS 28.632.

NOTE: The combination of isInvariant=true AND isWritable=true can not be represented in YANG. YANG does not differentiate between the initial setting and a subsequent changing of an attribute. 3GPP defined the invariant extension statement to mark this 3GPP property. Generally, extensions are not understood or enforced by standard YANG tools, they need extra SW implementation.

6.2.20 isReadable/isWritable

Reference [Error: Reference source not found] clause 5.2.1.1

6.2.20.1 YANG mapping

isReadable=false attributes can not be represented in YANG. Assumed not to be a problem. A YANG extension could be defined to handle it if needed.

Attributes with the properties isReadable=true AND isWritable=false shall be mapped to YANG config=false leafs/leaf-lists/lists. As config=false is inherited down the containment tree, it should not be placed on each leaf, leaf-list, etc. once the containing list/container is marked config false;

Attributes with the properties isReadable=true AND isWritable=true shall be mapped to YANG config=true leafs/leaf-lists/lists. "config true;" should not be explicitly declared as that is the default case.

6.2.21 isOrdered

Reference [Error: Reference source not found] clause 5.2.1.1

6.2.21.1 YANG mapping

For isWritable=true attributes the property isOrdered=true shall be mapped to the "ordered-by user;" YANG statement. For isWritable=false attributes the isOrdered property shall be described in the description statement of the YANG leaf-list, list representing the attribute.

Note: The "ordered-by user" statement is ignored in YANG if the leaf-list or list is config=false.

6.2.22 isUnique

Reference [Error: Reference source not found] clause 5.2.1.1

6.2.22.1 YANG mapping

The property isUnique=True shall be mapped to the YANG "unique" statement. Leaf-list are always unique in YANG, no marking needed.

6.2.23 allowedValues

Reference [Error: Reference source not found] clause 5.2.1.1

6.2.23.1 YANG mapping

For attributes with a type=integer or a user-defined type based on integers allowedValues shall be mapped to a YANG "range" statement with specific values.

For attributes with a type=string or a user-defined type based on string allowedValues shall be mapped either to an enumerated YANG type or to a sting with alternatives defined using the YANG "pattern" statement.

For attributes with a type=enumeration or a user-defined type based on enumeration allowedValues shall be mapped to a YANG enumeration type restricted with YANG "enum" substatements. (https://tools.ietf.org/html/rfc7950#section-9.6.3)

6.2.24 Xor constraint

Reference [Error: Reference source not found] clause 5.2.10

6.2.24.1 YANG mapping

Model elements with a Xor constraint shall be mapped to the YANG "choice" statement.

6.2.25 ProxyClass

Reference [Error: Reference source not found] clause 5.3.1

6.2.25.1 YANG mapping

A proxyclass is not directly mapped to YANG. A proxyclass represents a number of specific classes. Attributes, links, methods (or operations), and interactions that are present in the proxyclass shall be modelled in the represented specific classes.

6.2.26 SupportQualifier

6.2.26.1 Introduction

Reference [3] clause 6 – Qualifiers

6.2.26.2 YANG mapping

SupportQualifier=M is the default case in YANG so it needs no mapping.

SupportQualifier=O shall be mapped the same way as SupportQualifier=M. Just like in the other solution sets the supportQualifier shall not be directly visible in the 3GPP Stage 3 YANG model. The support is indicated the following way:

– If the vendor supports an optional item, there is no further modeling needed

– If the vendor does not support the optional item, it needs to create a separate vendor specific YANG module and include a “deviation” statement in it formally declaring the non-supported parts. A single YANG module may contain any number of deviations. E.g.:

deviation /ManagedElement/attributes/optionalAttribute {deviate not-supported;}

SupportQualifier=CO {if the item is not supported) is mapped the same way as a not supported SupportQualifier=O item.

SupportQualifier=CM & CO (if item is supported) shall be mapped as a SupportQualifier=M item, also considering the following:

– if the condition can be expressed with XPATH, an additional "when" statement shall be used.

– otherwise make the data node non-mandatory and define the condition in the description statement.

6.2.27 isNotifyable

6.2.27.1 Introduction

Reference TS 32.156 [3] clause 5.2.1.1

6.2.27.2 YANG mapping

Attributes that are isNotifyable=False shall be marked with the "yext3gpp:notNotifiable" YANG extension statement defined in the YANG module _3gpp-common-yang-extensions.yang.

Attributes that are isNotifyable=True shall not be marked in any way, as it is a default case.

Annex A (informative):
Example usage of the template for one management capability

4 Management capabilities

4.1 Monitoring the number of active UEs

4.1.1 Description

This management capability allows the consumer to monitor and retrieve the number of active UEs statistics information.

4.1.2 Use cases

4.1.2.1 Monitor of the number of active UEs (UC-4GPM-1)

The number of the active UEs in each cell is a valuable measurment for operators to know how many UEs are with buffered data per cell basis. This kind of information can help operators to tune the admission control parameters for the cell and to do load balancing between cells to ensure that the target percentage or number of the UEs admitted achieve the target QoS. However, the number of single uplink or downlink UEs can not effectively reflect the actual number of active UEs either on the downlink or on the uplink in the network.

As the active UEs reflect UEs have data to transmit or receive , the ratio of the number of active UEs to the number of the RRC connected UEs can be established, which can be used to monitor the the cell. In addition, compared with the number of RRC connected users, the number of active UEs is a more effective measurement to reflect the control plane capacity of wireless network.

4.1.3 Requirements

Requirement label	Description	Related use case(s)
REQ-4GPM-MC-01	The MnS producer shall allow MnS consumers to monitor statistics on the number of active UEs	(UC-4GPM-1) Monitor of the number of active UEs

Annex B (informative):
Change history

Change history
Date	Meeting	TDoc	CR	Rev	Cat	Subject/Comment	New version
2019-09	SA#85					Change control version	16.0.0
2019-12	SA#86	SP-190172	0001	–	F	Implement Edithelp comments	16.1.0
2019-12	SA#86	SP-190172	0002	–	F	Solutions for Editor’s notes Not implemented due to CR clash (MCC)	16.1.0
2019-12	SA#86	SP-190172	0003	1	F	Resolution of Editors Note in clause W4.3 Class definitions not implemented due to CR clash (MCC)	16.1.0
2019-12	SA#86	SP-191166	0004	2	B	Additions to YANG style Guide	16.1.0
2020-03	SA#87E	SP-200169	0005	–	B	YANG Guidelines Update	16.2.0
2020-03	SA#87E	SP-200172	0006	–	F	Remove incorrect example from constraints table	16.2.0
2020-03	SA#87E	SP-200172	0007	–	F	Resolution of Editors Note in clause W4.3 Class definitions	16.2.0
2020-07	SA#88E	SP-200489	0008	1	B	Update YANG Guidelines	16.3.0
2020-07	SA#88E	SP-200490	0009	–	B	Update YANG Guidelines	16.3.0
2020-12	SA#90e	SP-201089	0011	–	F	Fix incorrect reference in notification template	16.4.0
2020-12	SA#90e	SP-201089	0012		F	Update thresholdCrossingNotification to be a common notification.	16.4.0
2020-12	SA#90e	SP-201052	0010	1	B	Import prefix rule for YANG	17.0.0
2021-03	SA#91e	SP-210155	0015	–	C	YANG containment mapping	17.1.0
2021-03	SA#91e	SP-210155	0016	–	C	Code begin end markers and longer prefix length	17.1.0
2021-06	SA#92e	SP-210407	0013	4	C	Update on template for requirement specifications	17.2.0
2021-09	SA#93e	SP-210878	0021	1	A	Align different (abbreviated) names for support qualifier to “S”	17.3.0
2021-09	SA#93e	SP-210887	0022	–	F	Change format for NRM stage 3 definition rules from JSON to YAML	17.3.0
2021-09	SA#93e	SP-210887	0023	–	B	Add motivation to requirements	17.3.0
2022-06	SA#96	SP-220509	0027	–	F	YANG Mapping Corrections	17.4.0
2022-09	SA#97e	SP-220859	0028	–	F	YANG Mapping Rule Corrections	17.5.0
2022-12	SA#98e	SP-221171	0030	–	A	Add missing mapping of isNotifyable	17.6.0