5.5.1 Defining a Vendor-Specific Extension to a Standard Data Model
Vendors can extend Broadband Forum Data Models in order to define their own items (e.g. vendor-specific objects, parameters, enumerations, patterns, profiles). Both Root and Service Data Models can be extended in this way; such extensions are defined in the same way Broadband Forum amendments extend Data Models. However, the name assigned to vendor- specific items will begin with X_<VENDOR>_, where <VENDOR> must be as defined in Section 3.3/TR-106 [3].
A vendor-specific XML Data Model contains one document element. The document’s file and spec attributes will have a vendor-specific doc number. The Broadband Forum model to be extended is imported and used to define the vendor-specific model.
The following listing is an example of a vendor-specific model named X_ACDC73_Device:2.1 (where the vendor’s designation is ACDC73). Note that the Device:2.1 model is imported into the vendor-specific document, and is used to define the vendor-specific model based on Device:2.1. The model is extended in order to add a vendor-specific object and parameter.
<?xml version="1.0" encoding="UTF-8"?>
<dm:document xmlns:dm="urn:broadband-forum-org:cwmp:datamodel-1-4" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="urn:broadband-forum-org:cwmp:datamodel-1-4 cwmp-datamodel-1-4.xsd" file="acdc73_tr-181-2-1-0.xml" spec="urn:acdc73:tr-181-2-1-0">
<description>Device:2.1 Data Model with vendor extensions.</description> ...
<import file="tr-181-2-1.xml" spec="urn:broadband-forum-org:tr-181-2-1"> <model name="Device:2.1"/>
</import>
<model name="X_ACDC73_Device:2.1" base="Device:2.1">
<object name="Device.ManagementServer.X_ACDC73_ExampleObject." ... > <description>...</description> <parameter name="ExampleParameter" ...> <description>...</description> <syntax> <unsignedInt/> </syntax> </parameter> ... </object> ... </model> </dm:document>
In the above example, ExampleParameter is a vendor-specific parameter but its name does not include the vendor prefix. This is because its parent object is vendor-specific. Vendor-specific items (e.g. objects, parameters, enumerations) will not be named with a vendor prefix when their parent object or parameter is vendor-specific. In other words, this vendor-prefix naming rule only applies to the boundary between the Broadband Forum items and vendor-specific items.
5.5.2 Defining a Vendor-Specific Service Data Model
Vendors can also define entirely new Service Data Models independent of the Broadband Forum models. In this case, the entire model is vendor-specific.
Defining such a vendor-specific Service Data Model is done in the same way as defining a Broadband Forum Service Data Model (see Section 5.4). The only difference is that the top-level items will be named with an X_<VENDOR>_ prefix, where <VENDOR> must be as defined in Section 3.3/TR-106 [3]. The following items will be named with a vendor prefix:
The model.
The top-level number-of-entries parameter. The top-level multi-instance service object.
Note that items defined within the top-level multi-instance object (e.g. objects, parameters, enumerations) will not be named with a vendor prefix.
The following listing is an example of such a vendor-specific Service Data Model (where the vendor’s designation is ACDC73). Note that document’s file and spec attributes have a vendor-specific doc number.
<?xml version="1.0" encoding="UTF-8"?>
<dm:document xmlns:dm="urn:broadband-forum-org:cwmp:datamodel-1-4" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="urn:broadband-forum-org:cwmp:datamodel-1-4 cwmp-datamodel-1-4.xsd" file="acdc73_example-1-0-0.xml" spec="urn:acdc73:example-1-0-0">
<description>Vendor ExampleService:1.0 Data Model.</description> ...
<model name="X_ACDC73_ExampleService:1.0" isService="true">
<parameter name="X_ACDC73_ExampleServiceNumberOfEntries" access="readOnly"> <description>{{numentries}}</description>
<syntax>
<unsignedInt/> </syntax> </parameter>
<object name="X_ACDC73_ExampleService.{i}." access="readOnly" minEntries="0" maxEntries="unbounded" numEntriesParameter="X_ACDC73_ExampleServiceNumberOfEntries"> <description>...</description> <parameter name="ExampleParameter" ...> <description>...</description> <syntax> <unsignedInt/> </syntax> </parameter> ... </object> </model> </dm:document>
6 DM XML Data Model Tutorials
This section provides guidance in defining DM Instance documents (called DM Instances for short). These documents are XML files that comply with the DM Schema (Appendix I). They are defined by the Broadband Forum in order to specify standard Data Models and by CPE vendors in order to specify vendor-specific Data Models. Such Data Models represent objects and parameters available to a range of device types (i.e. not specific to a particular device type). A DM Data Model can be specified using multiple DM Instance documents. This will include a primary DM Instance document (that defines the latest revision of a given model), previous DM Instance documents (that define the previous revisions of the model if present), as well as supporting DM Instance documents (that define elements such as components, data types, and bibliography). See Sections 4 and 5 for further introductory materials regarding DM Instances and Data Models.
Note – DM Instances (and DM Data Models) should not be confused with DT Instances (and DT Data Models), discussed in Section 7, which instead describe a CPE vendor’s Supported Data Model for a particular device type.