3 Object Definitions

3.1 General Notation

Parameter names use a hierarchical form similar to a directory tree. The name of a particular Parameter is represented by the concatenation of each successive node in the hierarchy separated with a “.” (dot), starting at the trunk of the hierarchy and leading to the leaves. When specifying a partial path, indicating an intermediate node in the hierarchy, the trailing “.” (dot) is always used as the last character.

Parameter names MUST be treated as case sensitive. The name of each node in the hierarchy MUST start with a letter or underscore, and subsequent characters MUST be letters, digits, underscores or hyphens. The terms “letter” and “digit” are as defined in the XML specification [Appendix B/8].

Hyphens can easily be confused with the discretionary hyphens that are sometimes inserted by hyphenation algorithms. For this reason, the names of nodes in the hierarchy SHOULD NOT include any hyphens. Additionally, the names of nodes in the hierarchy SHOULD NOT start with underscores. In BBF standards, the names of nodes in the hierarchy always start with an upper-case letter and never include any hyphens or underscores (see C.3.1 for the corresponding normative requirement).

Where multiple instances of an object can occur, the placeholder node name {i} is shown. In actual use, this placeholder is to be replaced by an Instance Identifier.

3.2 Data Types and Representation

Parameters make use of a limited subset of the default SOAP data types. The supported data types are defined by the DM Schema and are also listed in A.2.3.

The named data types that specify the representations of IP addresses, MAC addresses etc, are defined in a DM Instance document (see Annex A). The XML file with those definitions and the corresponding HTML file can be found in the data model resources page. Note that this DM Instance defines named data types that are expected to be used in several data model definitions; it is possible to define local named data types in any DM Instance document.

The following sub-sections specify additional rules governing parameter value representation within XML documents.

3.2.1 Date and Time Rules

All times MUST be expressed in UTC (Universal Coordinated Time) unless explicitly stated otherwise in the definition of a parameter of this type.

If absolute time is not available to the Agent, it SHOULD instead indicate the relative time since boot, where the boot time is assumed to be the beginning of the first day of January of year 1, or 0001 01 01T00:00:00. For example, 2 days, 3 hours, 4 minutes and 5 seconds since boot would be expressed as 0001 01 03T03:04:05. Relative time since boot MUST be expressed using an untimezoned representation. Any untimezoned value with a year value less than 1000 MUST be interpreted as a relative time since boot.

If the time is unknown or not applicable, the following value representing “Unknown Time” MUST be used: 0001-01-01T00:00:00Z. For an infinite timeline, the following value representing “Infinite Time” MUST be used: 9999-12-31T23:59:59Z.

Any dateTime value other than one expressing relative time since boot (as described above) MUST use UTC timezoned representation (that is, it MUST include a timezone suffix of “Z”, “-00:00” or “+00:00”).

3.2.2 Comma-separated Lists

For strings that are defined to contain comma-separated lists, the format is defined as follows. Between every pair of successive items in a comma-separated list there MUST be a separator. The separator MUST include exactly one comma character, and MAY also include one or more whitespace characters before or after the comma. The entire separator, including any whitespace characters, MUST NOT be considered part of the list items it separates. The last item in a comma-separated list MUST NOT be followed with a separator. Individual items in a comma-separated list MUST NOT include a whitespace or comma character within them. Any whitespace or comma characters within an item value MUST be escaped using percent-encoding as specified in RFC 3986 [Section 2.1/9].

It is possible to create a list of lists, although other solutions SHOULD be preferred when possible. If a string contains a list of lists, the rules of the previous paragraph imply that the comma separators of the inner list will be percent encoded. For example, a three element list with elements “a”, “b,c” (a two element list) and “d” could be represented as “a,b%2Cc,d”. In order to avoid the need to percent encode the inner separators, inner lists MAY be “protected” by placing them within square brackets, e.g. the above list could be represented as “a,[b,c],d”. In order to avoid ambiguity (a Controller that didn’t understand the new syntax would interpret “a,[b,c],d” as the four element list “a”, “[b", "c]”, “d”), the data type and/or parameter definition MUST explicitly state that the new syntax is supported (A.2.3.1, A.2.7.1).

3.2.3 Parameters that Reference Parameters or Objects

For string parameters that are defined to contain the hierarchical Path Name of an object (or for each item in parameters that are defined to contain comma-separated lists of object Path Names), the representation of the object name MUST NOT include a trailing “dot.” An example of a parameter of this kind in the TR-181i2 [3] Device:2 data model is Device.InterfaceStack.{i}.LowerLayer. For this parameter, the following is an example of a properly formed value:

Device.Ethernet.Interface.1

Path Names in parameter values MUST always be full Path Names. For CWMP there is an exception such that a path that begins with a dot is relative to the Root or Service Object. For example, in the Device Root Object, a parameter value of “.DeviceInfo” always means “Device.DeviceInfo”. NOTE: This exception does NOT hold for USP.

In order to be able to use reference parameters as unique keys (A.2.10.1), their Path Names MUST conceptually be converted to full Path Names before being compared. For example, in the Device Root Object, “.DeviceInfo.” and “Device.DeviceInfo.” would compare as equal. If a reference parameter is list-valued, i.e. it is a list of Path Names or Instance Numbers, the parameter value MUST conceptually be regarded as a set when being compared, i.e. the comparison has to ignore the item order and any repeated items. For example, “1,2,1” and “2,1” would compare as equal because both reference instances 1 and 2.

References are defined as strong or weak in the data model. A strong reference always either references an existing parameter or object, or else is a null reference. On the other hand, a weak reference does not necessarily reference an existing parameter or object.

3.2.4 Units Conventions

For numeric parameters whose values are defined in terms of units, bit and byte-related units will always refer to powers of 2. For example, a kilobyte will always be 1024 bytes, a megabyte always 1024 * 1024 bytes, etc.

3.2.5 Default Maximum String Length

For string-valued parameters, a maximum length is either explicitly indicated or implied by the size of the elements composing the string. For strings in which the content is an enumeration, the longest enumerated value determines the maximum length. Similarly, for strings in which the content is a pattern, the longest possible matching value determines the maximum length. For strings in which the content is a list, the maximum number of items and the individual item lengths can help to determine the maximum string length.

3.3 Vendor-Specific Elements

A vendor MAY extend the standardized data model with vendor-specific elements (parameters, objects, commands, events). Vendor-specific elements MAY be defined either in a separate naming hierarchy or within the standardized naming hierarchy.

The name of a vendor-specific parameter, object, command, or event that is not contained within another vendor-specific object MUST have the form:

X_<VENDOR>_VendorSpecificName

In this definition <VENDOR> is a unique vendor identifier, which MAY be either an OUI or a domain name. The OUI or domain name used for a given vendor-specific parameter MUST be one that is assigned to the organization that defined this parameter (which is not necessarily the same as the vendor of the Agent). An OUI is an organizationally unique identifier as defined in [10], which MUST be formatted as a six-hexadecimal-digit string using all upper-case letters and including any leading zeros. A domain name MUST be upper case with each dot (“.”) replaced with a hyphen or underscore.

The VendorSpecificName MUST NOT contain a “.” (period) or a space character.

Note – the use of the string “X_” to indicate a vendor-specific parameter implies that no standardized parameter can begin with “X_”.

The name of a vendor-specific element that is contained within another vendor-specific object which itself begins with the prefix described above need not itself include the prefix.

The full Path Name of a vendor-specific element MUST NOT exceed 256 characters in length.

Below are some example vendor-specific element names:

A parameter:

Device.UserInterface.X_012345_AdBanner

A single-instance object:

Device.X_EXAMPLE-COM_MyConfig.Status

A command:

Device.X_EXAMPLE-COM_MyCommand()

An event:

Device.X_EXAMPLE-COM_MyEvent!

When appropriate, a vendor MAY also extend the set of values of an enumeration. If this is done, the vendor-specified values MUST be in the form “X_<VENDOR>_VendorSpecificValue”. The total length of such a string MUST NOT exceed 31 characters.