Updating an Existing Parameter Definition

Sometimes an existing parameter needs to be updated. This is done using a parameter element (I.10) within a new revision of the document that defined the parameter in question. This implies that the parameter’s other parent elements (e.g. object, model or component) will also be updated.

Note – The syntax for modifying a parameter is the same as for initially creating it, but there are rules. See Section A.2.10.1/TR-106 [3] for details.

An update to a parameter is a parameter definition that is based on the existing parameter. This is characterized by the use of the parameter/@base attribute, which indicates the name of the existing parameter being updated. Note that the parameter/@name attribute, which is used in the initial definition of a parameter, is not used when updating a parameter.

The updated definition will contain changes and additions to the existing parameter. It should not re-define those portions of the existing parameter that have not changed. Generally, this means that optional parameter attributes that are not changing are not re-specified (e.g. status, activeNotify), and that elements within the parameter that are not changing are also not re- specified (e.g. description, syntax). See Appendix I.10 for a full list of attributes and elements and whether they are optional or required.

Note – Required parameter attributes are always specified regardless of whether or not they are being changed, because if they were not then schema validation would fail. Optional parameter attributes, while generally not specified unless they are changing, may be re-specified if the author deems it appropriate. Common reasons to update a parameter include:

Change an attribute value; e.g. set status to deprecated Update its description

Change its syntax; e.g. specify a default value, or narrow its set (or range) of valid values The following example illustrates updates to two parameters (the first listing is the initial parameter definitions in tr-181-2-0-1 and the second listing is the updates in the much later tr- 181-2-2-0). The Protocol parameter has its data type updated to indicate a maximum value, and the SourceUserClassID parameter just has its description updated. As expected, the updates are

within a new document revision and the parameters’ parent elements are also updated (in this case, their object and model).

<dm:document xmlns:dm="urn:broadband-forum-org:cwmp:datamodel-1-2" ... spec="urn:broadband-forum-org:tr-181-2-0-1"> ... <model name="Device:2.0"> ... <object name="Device.QoS.Classification.{i}." ...> ...

<parameter name="Protocol" access="readWrite"> <description>Classification criterion.

Protocol number. A value of -1 indicates this criterion is not used for classification. </description>

<syntax> <int>

<range minInclusive="-1"/> </int>

<default type="object" value="-1"/> </syntax>

</parameter>

<parameter name="SourceUserClassID" access="readWrite"> <description>Classification criterion.

A hexbinary string used to identify one or more LAN devices, value of the DHCP User Class Identifier (Option 77) as defined in...

</description> <syntax> <hexBinary>

<size maxLength="65535"/> </hexBinary>

<default type="object" value=""/> </syntax> </parameter> ... </object> ... </model> </dm:document> <dm:document xmlns:dm="urn:broadband-forum-org:cwmp:datamodel-1-3" ... spec="urn:broadband-forum-org:tr-181-2-2-0"> ...

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

<object base="Device.QoS.Classification.{i}." ...> ...

<parameter base="Protocol" access="readWrite"> <syntax>

<int>

<range minInclusive="-1" maxInclusive="255"/> </int>

<default type="object" value="-1"/> </syntax>

</parameter>

<parameter base="SourceUserClassID" access="readWrite"> <description action="replace">Classification criterion.

A hexbinary string used to identify one or more LAN devices, value of the DHCP User Class Identifier. The DHCP User Class Identifier is Option 77 (as defined in... </description>

</parameter> ...

... </model> </dm:document>

A few things should be observed within the updated document (in the second listing) that applies whenever a parameter definition is updated:

The parameter/@base attribute is used to reference the existing parameter definition. The parameters’ required attributes are present (even though none were changed).

The parameters’ optional attributes are not present since none changed (though it is not an error to re-specify them). When omitted, the presumption is that their previous settings will carry forward unchanged.

The Protocol parameter’s description is omitted since it was not updated. No need to re- specify a description if it is not changing. When omitted, the presumption is that the existing description is carried forward.

The SourceUserClassID parameter’s syntax is omitted since it was not updated. No need to re-specify the syntax if it is not changing. When omitted, the presumption is that the existing syntax is carried forward.

The Protocol parameter’s updated data type definition is a restriction (not an extension) of its prior definition. Updates to a parameter’s data type must obey the base type restriction rules of Section A.2.3.8/TR-106 [3] (i.e. a valid value of the updated data type definition will also be a valid value of its original data type definition; if a facet present in the base type is re-specified it must be fully specified; etc.).

The Protocol parameter’s default value is re-specified even though it was not updated. This is truly redundant (i.e. if omitted, the existing parameter default would be carried forward). However, it is not an error to re-specify unnecessary portions of the syntax, perhaps the author wished to provide some context for readability, but doing so could introduce errata.

Note – In the above example, it is not shown in the second listing, but the previous Device:2.1 model must be imported before it can be used to define the updated Device:2.2 model. See 6.4.2 for details on updating an existing model.

When an existing parameter needs be deprecated, obsoleted, or deleted, this is done by updating its parameter/@status attribute. The parameter’s description must also be updated to include an explanation of why the status was changed. See Section 6.10 for details.