2 Architecture

All elements described hereunder apply to both CWMP and USP, unless specifically mentioned otherwise.

2.1 Data Hierarchy

The data model for a Agent will follow a common set of structural requirements. The detailed structure depends on the nature of the Agent.

An Agent’s data model will always have a single Root Object, which will be called “Device.”.

The Root Object contains three types of sub-elements: the Objects defined in TR-181i2 [3], Components defined in TR-181i2 or other specifications such as TR-143 [6], and a single “Services” object that contains all Service Objects associated with specific services.

A single Agent might include more than one Service Object. For example, a device that serves both as a VoIP endpoint and a game device, might include both VoIP-specific and game-specific Service Objects.

A single Agent might also include more than one instance of the same type of Service Object. An example of when this might be appropriate is an Agent that provides an instance of the TR-140 [7] StorageService for each of the device’s attached disks.

2.1.1 Data Hierarchy Requirements

A CWMP or USP data model MUST adhere to the following structural requirements:

  1. A root data model definition MUST contain exactly one Root Object, called “Device.”.

  2. A Root Object definition MUST contain exactly one “Services.” object.

  3. A service data model definition MUST define an object hierarchy that starts just under the “Device.Services.” object.

  4. For each Multi-Instance Object defined, a data model MUST also define a corresponding parameter indicating the number of instances of the Multi-Instance Object. The name of this parameter MUST be the name of the object concatenated with “NumberOfEntries”. This parameter MUST appear in the same object as the Multi-Instance Object it is related to.

Formally, the top level of the data hierarchy is defined as follows:

    Element = "Device"
            | "Device." TR-181DeviceObject
            | "Device.Services." ServiceObject "NumberOfEntries"
            | "Device.Services." ServiceObject ".{i}"

    TR-181DeviceObject = // As defined in TR-181i2, e.g. "UserInterface" or "ManagementServer"

    ServiceObject = // As defined in other specs, e.g. TR-140

2.1.2 The Supported Data Model and the Instantiated Data Model

There is a distinction between an Agent’s Supported Data Model and its Instantiated Data Model.

TR-181i2 [3] defines a SupportedDataModel Object that allows an Agent to indicate its Supported Data Model to a Controller, which assists the Controller in managing that device.

The SupportedDataModel object has the following properties:

  1. It contains a list of URLs, each of which allows the Controller to determine details of part of the Supported Data Model.

  2. When the Supported Data Model changes, e.g. because software is loaded or unloaded, entries are added to or removed from this list of URLs.

This object is not used with USP. TR-369 [2] defines the GetSupportedDM message to provide this information.

2.2 Object Versioning

To allow the definition of a Service Object or Root Object to change over time, the definition of a Service Object or Root Object MUST have an explicitly specified version.

Version numbering of Service Objects and Root Objects is defined to use a major/minor version numbering convention. The object version is defined as a pair of integers, where one integer represents the major version, and the second integer represents the minor version. The version MUST be written with the two integers separated by a dot (Major.Minor).

The first version of a given object SHOULD be defined as version “1.0”.

For each subsequent version of the object, if the later version is compatible with the previous version, then the major version SHOULD remain unchanged, and the minor version SHOULD be incremented by one. For example, the next compatible version after “2.17” would be “2.18”. The requirements for a version to be considered compatible with an earlier version are described in Section 2.2.1.

For each subsequent version of the object, if the later version is not compatible with the previous version, then the major version MUST increment by one, and the minor version MAY reset back to zero. For example, the next incompatible version after “2.17” might be “3.0”.

2.2.1 Requirements for Compatible Versions

For one version of an object to be considered compatible with another version, the later version MUST be a strict superset of the earlier version. Using major/minor versioning, this requirement applies only between minor versions that share the same major version.

More specifically, this requires the following of the later version with respect to all earlier versions to which it is to be compatible:

The goal of the above definition of compatibility is intended to ensure bi-directional compatibility between a Controller and Agent. Specifically that:

2.2.2 Version Notation

For objects, the following notation is defined to identify specific versions:

Notation Description Example
ObjectName:Major.Minor Refers to a specific version of the object. Device:2.0
ObjectName:Major Refers to any minor version of the object with the specified major version. Device:2
ObjectName Refers to any version of the object. Device

Note that the version notation defined here is only to be used for purposes of documentation. The actual names of objects and parameters in the data model MUST NOT include version numbers.

2.3 Profiles

Note: Originally, profiles were seen as a means of limiting the variability that a Controller needs to accommodate among various devices that it might manage. This feature is now provided:

A profile is a named collection of requirements associated with a given object. An Agent can adhere to zero or more profiles. Adherence to a profile means that the Agent supports all of the requirements defined by that profile. The use of profiles gives Service Providers a shorthand means of specifying data model support requirements.

The following sections define the conventions to be used when defining profiles associated with Data Models.

2.3.1 Scope of Profiles

A given profile is defined only in the context of a specific Service Object or Root Object with a specific major version. For each profile definition, the specific object name and major version to which the profile is to apply MUST be explicitly identified.

A profile’s name MUST be unique among profiles defined for the same object and major version, but a name MAY be reused to define a different profile for a distinct combination of object name and major version. For example, if we define profile “A” associated with object “X:2” (major version 2 of object X), the same name “A” might be used to define a different profile for object “Y:1” or for object “X:3”.

A given profile is defined in association with a minimum minor version of a given object. The minimum REQUIRED version of an object is the minimum version that includes all of the REQUIRED elements defined by the profile. For each profile definition, the specific minimum version MUST be explicitly identified.

2.3.2 Multiple Profile Support

For a given type of Service Object or Root Object, multiple profiles MAY be defined. Profiles MAY be defined that have either independent or overlapping requirements.

2.3.3 Profile Versions

To allow the definition of a profile to change over time, the definition of every profile MUST have an associated version number.

Version numbering of profiles is defined to use a minor-only version numbering convention. That is, for a given profile name, each successive version MUST be compatible with all earlier versions. Any incompatible change to a profile MUST use a different profile name.

For one version of a profile to be considered compatible with another version, the later version MUST be a strict superset of the earlier version. This requires the following of the later version with respect to all earlier versions to which it is to be compatible:

For profiles, the following notation is defined to identify specific versions:

Notation Description Example
ProfileName:Version Refers to a specific version of the profile. Baseline:1
ProfileName Refers to any version of the profile. Baseline

ProfileName 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, ProfileName SHOULD NOT include any hyphens. In BBF standards, ProfileName will always start with an upper-case letter (or an underscore for an internal profile) and will never include any hyphens (see C.3.1 for the corresponding normative requirement).

2.3.4 Baseline Profiles

For every Service Object (and Root Object) there SHOULD be at least one profile defined. In many cases it is desirable to define a Baseline profile that indicates the minimum requirements REQUIRED for any device that supports that Object.

2.3.5 Types of Requirements in a Profile

Because a profile is defined within the context of a single Object (and major version), all of the requirements associated with the profile MUST be specific to the data model associated with that object.

Profile requirements can include any of the following types of requirements associated with an Object’s data model:

For each of the requirement categories listed above, a profile can define the requirement unconditionally, or can place one or more conditions on the requirement. For example, a profile might require that a Parameter be supported for reading only if the device supports some other Parameter or Object (one that is not itself REQUIRED by the profile). Such conditions will be directly related to the data model of the overall object associated with the profile.

Because a device has to be able to support multiple profiles, all profiles MUST be defined such that they are non-contradictory. As a result, profiles MUST only define minimum requirements to be met, and MUST NOT specify negative requirements. That is, profiles will not include requirements that specify something that is not to be supported by the device, or requirements that exclude a range of values.

2.4 DEPRECATED and OBSOLETED Items

The key word “DEPRECATED” in a data model definition is to be interpreted as follows: This term refers to an object, parameter or parameter value that is defined in the current version of the standard but is meaningless, inappropriate, or otherwise unnecessary. It is intended that such objects, parameters or parameter values will be removed from the next major version of the data model. Requirements on how to interpret or implement deprecated objects, parameters or parameter values are given below. For more information on how to interpret or implement specific deprecated objects, parameters or parameter values, refer to the definition of the object or parameter.

The key word “OBSOLETED” in a data model definition is to be interpreted as follows: This term refers to an object, parameter or parameter value that meets the requirements for being deprecated, and in addition is obsolete. Such objects, parameters or parameter values can be removed from a later minor version of a data model, or from a later version of a profile, without this being regarded as breaking backwards compatibility rules. Requirements on how to interpret or implement obsoleted objects, parameters or parameter values are given below. For more information on how to interpret or implement specific obsoleted objects, parameters or parameter values, refer to the definition of the object or parameter.

2.4.1 Requirements for DEPRECATED Items

This section defines requirements that apply to all DEPRECATED objects, parameters and parameter values unless specifically overridden by the object or parameter definition.

Data model requirements:

  1. The definition of a DEPRECATED parameter, object or parameter value MUST include an explanation of why the item is deprecated.

  2. The definition of a DEPRECATED parameter, object or parameter value MAY specify further requirements relating to the item; such requirements MAY override general Agent or Controller requirements regarding DEPRECATED elements specified in TR-069 [1] or TR-369 [2].

Agent requirements:

  1. A DEPRECATED parameter MUST have a value which is valid for its data type and fulfils any range (for numeric parameters), length (for string, base64 or hexBinary parameters) and enumerated value (for string parameters) requirements.

  2. Detailed behavioral requirements for a DEPRECATED parameter, e.g. that its value is a unique key, MAY be ignored by the Agent.

  3. The Agent MUST, if such operations are permitted by the data model definition, permit creation of DEPRECATED objects, modification of DEPRECATED parameters, and setting of DEPRECATED parameter values. However, it MAY choose not to apply such changes to its operational state.

  4. Regardless of whether DEPRECATED changes are applied to the Agent’s operational state, a read of a DEPRECATED writable parameter SHOULD return the value that was last written, i.e. the Agent is expected to store the value even if it chooses not to apply it to its operational state.

  5. The Agent MAY reject an attempt by a Controller to set any parameter to a DEPRECATED value.

Controller requirements:

  1. The Controller SHOULD NOT create DEPRECATED objects, modify DEPRECATED parameters, or set DEPRECATED parameter values.

  2. The Controller SHOULD ignore DEPRECATED objects, parameters and parameter values.

  3. The Controller SHOULD NOT set a DEPRECATED parameter to a value that is invalid for its data type or fails to fulfill any range (for numeric parameters), length (for string, base64 or hexBinary parameters) or enumerated value (for string parameters) requirements.

  4. The Controller SHOULD NOT set any parameter to a DEPRECATED value.

2.4.2 Requirements for OBSOLETED Items

This section defines requirements that apply to all OBSOLETED objects, parameters or parameter values unless specifically overridden by the object or parameter definition.

An OBSOLETED object, parameter or parameter value MUST meet all the requirements of the previous section. In addition, the following requirements apply.

  1. An OBSOLETED object, parameter or parameter value MAY be removed from a later minor version of a data model without this being regarded as breaking backwards compatibility rules.

  2. An OBSOLETED object, parameter or parameter value MUST NOT be removed from the current version of a profile, but MAY be removed from a later version of a profile without this being regarded as breaking backwards compatibility rules.

  3. A data model definition MUST include a list of those OBSOLETED objects, parameters or parameter values that have been removed from the data model or from its profiles. This is to prevent future namespace conflicts.