A named data type is a custom data type that is usually defined within the central tr-106-1-0-0- types.xml file using the top-level dataType element (I.4). This should not be confused with the dataType element that can appear within parameter definitions, which is just a data type reference (a reference to a named data type defined elsewhere) rather than a data type definition. A named data type should be defined when there is a set of data requirements that can apply to a range of parameters. For example, an IP address or a MAC address. By defining and using a named data type, it guarantees that these data requirements will be applied consistently.
A named data type is defined in terms of one of the built-in primitive data types (e.g. unsignedInt), or defined in terms of another named data type from which it inherits part of its definition.
The two varieties of named data types can be characterized as: basic and derived. A derived type will inherit from another named data type (either basic or derived). A basic type inherits nothing and is defined using one of the built-in primitive data types.
The ultimate purpose in defining a named data type is in specifying a parameter’s type (i.e. within a parameter/syntax/dataType element). Using a named data type is a consistent way to associate a set of data requirements with a parameter. See Section 6.6.1.2 for details. Note – The DM Schema indicates that named data types are defined under a document element, which means that data types can be defined within any XML file. This might be useful when a draft document is in development. However, the convention is to limit data type definitions to the central tr-106-1-0-0- types.xml file for all published documents.
Note – The tr-106-1-0-0-types.xml file name does not change when it is updated.
Note – A Data Model file will need to import tr-106-1-0-0-types.xml in order to use its data types. See Section 6.3.1 for details.
6.2.1 Define a Basic Named Data Type
A basic named data type is defined using one (and only one) of the built-in primitive types. These built-in types are (see I.12):
base64 boolean dateTime hexBinary int long string unsignedInt unsignedLong
To add a new data type to tr-106-1-0-0-types.xml, simply insert a dataType element and its related sub-elements (I.4). At a minimum, the data type needs to include a name, a description, and exactly one built-in type.
The following listing illustrates the definition of the StatsCounter32 data type (defined using the primitive unsignedInt type).
<dm:document xmlns:dm="urn:broadband-forum-org:cwmp:datamodel-1-3" ... spec="urn:broadband-forum-org:tr-106-1-0-0">
...
<dataType name="StatsCounter32">
<description>A 32-bit statistics parameter, e.g. a byte counter.</description> <unsignedInt/>
</dataType> ...
</dm:document>
The description is optional but recommended, and can be used to specify additional data requirements. The name must be unique as it is used to identify the data type across Data Models. The name must begin with an upper-case letter, in order to avoid confusion with built-in data types.
The following listing illustrates the definition of the MACAddress data type (defined using the primitive string type).
<dm:document xmlns:dm="urn:broadband-forum-org:cwmp:datamodel-1-3" ... spec="urn:broadband-forum-org:tr-106-1-0-0">
...
<dataType name="MACAddress">
<description>All MAC addresses are ... strings of 12 hexadecimal digits ....</description> <string> <size maxLength="17"/> <pattern value=""/> <pattern value="([0-9A-Fa-f][0-9A-Fa-f]:){5}([0-9A-Fa-f][0-9A-Fa-f])"/> </string> </dataType> ... </dm:document>
Note that the built-in primitive type (e.g. string) can itself contain sub-elements (referred to as facets). See Appendix I.12 for details regarding the built-in data type elements and their sub- element facets. In the example above, the string is restricted to a maximum length of 17, and
conforms to a regex10 pattern of empty or 6 colon-separated pairs of hex digits.
6.2.2 Define a Derived Named Data Type
A derived named data type inherits its base definition from another (inherited) named data type. This is specified using the dataType/@base attribute. The base attribute cannot reference a built-in primitive data type.
10
To add a new data type to tr-106-1-0-0-types.xml, simply insert a dataType element and its related sub-elements (I.4). At a minimum, a derived data type needs to include a name and base attribute, and a description. The description is optional, but recommended.
The name must be unique, as it is used to identify the data type across Data Models. It must also begin with an upper-case letter in order to avoid confusion with built-in data types. The base attribute indicates the name of the existing named data type on which to base the new definition (i.e. the existing data type being inherited).
A derived data type is a restriction of the data type it is inheriting. Either its description will specify such restrictions, or (preferably) the data type will contain facet sub-elements that define these restrictions explicitly. See Appendix I.13 for details regarding data type facets. Common facets used within named data types include: size, range, units, pattern, and enumeration.
The following listing illustrates the definition of two named data types: IPAddress (a basic type defined with the primitive string type) and IPv4Address (a derived type that inherits from IPAddress). The facets within the IPv4Address data type indicate that the string has a max length
of 15 (rather than 45 characters) and must conform to a specific regex11 pattern.
<!DOCTYPE cwmp-datamodel-entities [ <!ENTITY dot "\."> <!ENTITY octet "(25[0-5]|2[0-4][0-9]|[01]?[0-9]?[0-9])"> <!-- 0 to 255 --> ]> <dm:document xmlns:dm="urn:broadband-forum-org:cwmp:datamodel-1-3" ... spec="urn:broadband-forum-org:tr-106-1-0-0"> ... <dataType name="IPAddress"> <description>
IP address, i.e. IPv4 address (or IPv4 subnet mask) or IPv6 address. </description> <string> <size maxLength="45"/> </string> </dataType>
<dataType name="IPv4Address" base="IPAddress"> <description>
IPv4 address (or subnet mask).
Can be any IPv4 address that is permitted by the ''IPAddress'' data type. </description> <size maxLength="15"/> <pattern value=""/> <pattern value="(&octet;˙){3}&octet;"/> </dataType> ... </dm:document>
Note – In the above example, the IPv4Address named data type is derived from an existing data type (i.e. from the IPAddress named data type). In such cases the base type restriction rules of Section A.2.3.8/TR- 106 [3] must be obeyed. Base type restriction means that a valid value of a derived data type will always be a valid value for its base type.
11