Basic Walkthrough – Defining an Amendment to a Root Data Model

5.3 DEFINING ROOT DATA MODELS

5.3.4 Basic Walkthrough – Defining an Amendment to a Root Data Model

This section outlines the basic steps involved in extending an existing Root Data Model (i.e.

creating a minor revision). This applies whether it is the first or nth revision to the Data Model.

Examples include:

InternetGatewayDevice:1.4 (declared in tr-098-1-2-0.xml) Device:1.5 (declared in tr-181-1-0-0.xml)

Device:2.2 (declared in tr-181-2-2-0.xml)

The main differences in writing an amendment, rather than an initial, Root Data Model are: The previous version of the Data Model needs to be imported

The model/@base attribute references the previous version of the Data Model that was imported.

For object, parameter, and profile definitions being updated, their object/@base, parameter/@base, and profile/@base attributes are used to reference the previous definition.

For descriptions being updated, the description/@action attribute indicates how the specified description will be applied to its previous definition (i.e. prefix, append, replace).

This walkthrough is an example of writing the Device:2.2 Data Model.

To begin, the XML Data Model file contains one document element (as required for all DM Instance documents). Note that the spec attribute references the specification that defined the Data Model, TR-181 Issue 2 Amendment 2 in this case. Also, the DM Schema v1.3 specified by the dm and schemaLocation attributes was the latest version available when the Device:2.2

Data Model was written6.

<?xml version="1.0" encoding="UTF-8"?>

<dm:document xmlns:dm="urn:broadband-forum-org:cwmp:datamodel-1-3" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xsi:schemaLocation="urn:broadband-forum-org:cwmp:datamodel-1-3 cwmp-datamodel-1-3.xsd” spec="urn:broadband-forum-org:tr-181-2-2-0">

<description>Device:2.2 Data Model.</description>

...

</dm:document>

Import previous version of the Data Model (i.e. import Device:2.1 from TR-181 Issue 2 Amendment 1), and then define the new Device:2.2 version of the Data Model which will be based on (built on top of) the existing definitions imported from Device:2.1.

The model element uses its base attribute to indicate which Data Model (and version) is being extended, and its name attribute to indicate the name (and version) of the updated Data Model. Note that the Data Model’s minor version is incremented by one.

</import>

<model name="Device:2.2" base=”Device:2.1”> ...

</model>

Import named data types that will be referenced in this revision of the Data Model.

Putting it all together we have:

<?xml version="1.0" encoding="UTF-8"?>

<dm:document xmlns:dm="urn:broadband-forum-org:cwmp:datamodel-1-3" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xsi:schemaLocation="urn:broadband-forum-org:cwmp:datamodel-1-3 cwmp-datamodel-1-3.xsd” spec="urn:broadband-forum-org:tr-181-2-2-0">

<description>Device:2.2 Data Model.</description>

</import>

<model name="Device:2.2" base=”Device:2.1”> ...

</model> ...

</dm:document>

Define an update to the existing ManagementServer object and to its existing ConnectionRequestURL parameter. Notice the use of the base attribute to reference existing objects and parameters. Update the parameter description by appending additional text to the end of its existing description (the action attribute set to “append” stipulates this behavior; cf. the “prefix” and “replace” action values).

Note that we are re-specifying the object and parameter attributes (e.g. access, minEntries, forcedInform, etc.) in order to mirror the original definition of these elements, and because in some cases these are required attributes and it would be a schema violation to omit them. We do not specify the object description (since we are not making changes to the existing text), and we do not specify the parameter syntax (since nothing in its syntax changed).

activeNotify="forceDefaultEnabled">

Note: If the ''host'' portion of the URL is a literal IPv6 address then it MUST be... </description>

</parameter> </object>

Define a new parameter under an existing object defined in an earlier version of the Data Model. Again, reference the existing object using the base attribute rather than name (i.e. declare rather than define). Note that defining new parameters in an amendment is done in the usual way using the name attribute. In this example we are defining a parameter that is a list of enumerated items.

<description>The DNS record types that are supported by the device.</description> <syntax> <list/> <string> <enumeration value="A"/> <enumeration value="AAAA"/> <enumeration value="SRV"/> <enumeration value="PTR"/> </string> </syntax> </parameter> </object>

Update an existing profile. The profile element uses the name attribute to define the new profile, but in this case the base attribute is also used to reference the existing profile that is being extended. The name of the profile is suffixed with its version number. The updated profile version number is one greater than the previous version. Objects and parameters declared within the profile are simply references (see ref attribute) to the actual object and parameters that were defined earlier in the Data Model.

</profile>

<?xml version="1.0" encoding="UTF-8"?>

<dm:document xmlns:dm="urn:broadband-forum-org:cwmp:datamodel-1-3" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xsi:schemaLocation="urn:broadband-forum-org:cwmp:datamodel-1-3 cwmp-datamodel-1-3.xsd” spec="urn:broadband-forum-org:tr-181-2-2-0">

<description>Device:2.2 Data Model.</description>

</import>

<model name="Device:2.2" base=”Device:2.1”> ...

activeNotify="forceDefaultEnabled"> <description action="append">

Note: If the ''host'' portion of the URL is a literal IPv6 address then it MUST be ... </description>

</parameter> </object>

In document TR-154 TR-069 Data Model XML User Guide (Page 37-41)