Annex A: CWMP Data Model Definition XML Schema

• A.1 Introduction
  • A.1.1 Character Encoding and Character Set
• A.2 Normative Information
  • A.2.1 Importing DM Instances
  • A.2.2 Descriptions
  • A.2.3 Data Types
  • A.2.4 Glossary, Abbreviations, Bibliography and Templates
  • A.2.5 Components
  • A.2.6 Root and Service Objects
  • A.2.7 Parameters
  • A.2.8 Commands (USP Only)
  • A.2.9 Events (USP Only)
  • A.2.10 Objects
  • A.2.11 Profiles
  • A.2.12 Modifications
  • A.2.13 Versions
• A.3 DM Schema
• A.4 DMR Schema

A.1 Introduction

The CWMP Data Model Definition XML Schema [11], or DM Schema, is used for defining CWMP [1] and USP [13] data models, and is specified in A.2.12.6.

DM Schema instance documents can contain any or all of the following:

• Data type definitions

• Root Object definitions (including profiles)

• Service Object definitions (including profiles)

• Component definitions

• Vendor extension definitions

Annex C contains some additional normative requirements that apply only to BBF standard DM Schema instance documents.

Most of the data model elements are common to CWMP and USP. Those that are specific to either protocol will be noted in the description.

A.1.1 Character Encoding and Character Set

BBF standard DM Schema instance documents use UTF-8 encoding and their character set is restricted to printable ASCII characters. See C.2 for the corresponding normative requirements.

A.2 Normative Information

It is possible to create instance documents that conform to the DM Schema but nevertheless are not valid data model definitions. This is because it is not possible to specify all the normative data model definition requirements using the XML Schema language. Therefore, the schema contains additional requirements written using the usual normative language. Instance documents that conform to the DM Schema and meet these additional requirements are referred to as DM Instances.

For example, the definition of the parameter element includes the following additional requirements on the name and base attributes:

    <xs:complexType name="ModelParameter">
      <xs:annotation>
        <xs:documentation>
        Parameter definition and
        reference.
        </xs:documentation>
      </xs:annotation>

      ...

      <xs:attribute name="name" type="tns:ParameterName">
        <xs:annotation>
          <xs:documentation>
          MUST be unique within the parent object
          (this is checked by schema validation).

          MUST be present if and only if defining a new
          parameter.
          </xs:documentation>
        </xs:annotation>
      </xs:attribute>

      <xs:attribute name="base" type="tns:ParameterName">
        <xs:annotation>
          <xs:documentation>
            MUST be present if and only if modifying an existing
            parameter.
          </xs:documentation>
        </xs:annotation>
      </xs:attribute>

      ...

    </xs:complexType>

In some cases, a requirement that is in fact implied by the DM Schema is emphasized within the schema via the xs:documentation element (the uniqueness requirement on the name is an example of this).

In other cases, a schema-implied requirement is not highlighted. For example, the name and base attributes are of type tns:ParameterName:

    <!DOCTYPE cwmp-datamodel [
      ...
      <!ENTITY name "([\i-[:]][\c-[:\.]]*)">
      ...
    ]>
      ...
      <xs:simpleType name="ParameterName">
        <xs:annotation>
          <xs:documentation>Parameter name (maximum length 256); the same as xs:NCName except that periods are not permitted.  This name MUST in addition follow the vendor-specific parameter name requirements of Section 3.3.</xs:documentation>
        </xs:annotation>
        <xs:restriction base="xs:token">
          <xs:maxLength value="256"/>
          <xs:pattern value="&name;"/>
        </xs:restriction>
      </xs:simpleType>

This states that the parameter name is a string that follows the following rules:

• It is derived from xs:token, which has a whitespace facet of “collapse”, meaning that any leading whitespace in the name will be ignored.

• It has a maximum length of 256 characters.

• Its first character matches the pattern “[\i-:]]”, which means “any character permitted as the first character of an XML name, except for a colon”, and any subsequent characters match the pattern “[\c-[:\.]]”, which means “any character permitted in an XML name, except for a colon and a dot”.

• It follows the vendor-specific parameter name requirements of Section 3.3.

The question of the location of the definitive normative information therefore arises. The answer is as follows:

• All the normative information in the main part of the document remains normative.

• The DM Schema, and the additional requirements therein, are normative. Some of these additional requirements are duplicated (for emphasis) in this Annex.

• The DM Schema references additional material in this Annex. Such material is normative.

• If the DM Schema conflicts with a normative requirement in the main part of the document, this is an error in the DM Schema, and the requirement in the main part of the document takes precedence.

A.2.1 Importing DM Instances

DM Instances are imported using the top-level import element. The DM Schema specifies that the DM Instance is located via the file attribute.

The rules governing the file attribute’s value and its use for locating the DM Instance are as follows:

• It MUST be a URL adhering to RFC 3986 [8].

• If the URL includes a scheme, it MUST be http, https or ftp.

• If the URL includes an authority, it MUST NOT include credentials.

• For standard BBF DM Instances, the rules that apply to the filename part (final path segment) of the A.2.1.1 BBFURL also apply to the filename part of this URL. This means that the corrigendum number can be omitted in order to refer to the latest corrigendum. See C.3.6 for the corresponding normative requirement.

• If the URL is a relative reference, processing tools MUST apply their own logic, e.g. apply a search path.

A.2.1.1 URI Conventions

The top-level spec attribute contains the URI of the associated specification document, e.g. the BBF Technical Report.

This URI SHOULD uniquely identify the specification. More than one DM Schema instance document MAY reference the same specification.

The top-level file attribute contains the name of the DM Schema instance document, e.g. the XML file that defines a given version of a data model.

The following rules apply to the value of the top-level spec attribute:

• For a BBF Technical Report, it will be of the form “urn:broadband-forum-org:tr-nnn-i-a-c”, where nnn is the specification number (including leading zeros), i is the issue number, a is the amendment number, and c is the corrigendum number. The issue, amendment and corrigendum numbers do not include leading zeros. For example, “urn:broadband-forum-org:tr-106-1-0” refers to TR-106 (Issue 1 Amendment 0), and “urn:broadband-forum-org:tr-106-1-2” refers to TR-106 (Issue 1) Amendment 2. See C.3.4 for the corresponding normative requirement.

• For specifications issued by other standards organizations, or by vendors, it SHOULD be of a standard form if one is defined. For example, RFC 2648 [7] specifies a syntax for referencing RFCs.

• Note that processing tools are likely to assume that all files that share a spec value are related to each other. Therefore, use of meaningful spec values is RECOMMENDED.

The following rules apply to the value of the top-level file attribute.

• For a BBF Technical Report, it will be of the form “tr-nnn-i-a-c.xml” or “tr-nnn-i-a-c-label.xml”, where nnn, i, a and c are the same as in the spec attribute. The label, which MUST NOT begin with a digit, is not needed if only one DM Schema instance document is associated with the specification. See C.3.5 for the corresponding normative requirement.

• It SHOULD be the same as the actual file name (omitting the directory name). Under some circumstances this will not be possible, e.g. because the content is stored in a database and not in a file system.

Formally, the values of the spec and file attributes are defined as follows:

    SpecAttr = SpecURI
    FileAttr = FileName
    SpecURI = BBFURI
            | OtherURI
    BBFURI = "urn:broadband-forum-org:" BBFDoc
    FileName = BBFDoc BBFSubDoc ".xml"
    BBFDoc = "tr-" BBFNumber BBFIssue BBFAmendment BBFCorrigendum
    BBFNumber = [DIGIT]{3,}     // including leading zeros, e.g. 069
    BBFIssue = "-" NoLeadingZeroPositiveNumber
    BBFAmendment = "-" NoLeadingZeroNumber
    BBFCorrigendum = "-" NoLeadingZeroNumber
    BBFSubDoc = "-" LABEL       // distinguishing label (not beginning with a digit)
              | ""              // not needed if only one DM Instance is associated with spec
    NoLeadingZeroNumber = [DIGIT]
                        | [NONZERODIGIT] [DIGIT]*
    NoLeadingZeroPositiveNumber = [NONZERODIGIT] [DIGIT]*
    OtherURI = <of a standard form if one is defined>

Standard BBF DM Instances can be accessed at the following URL:

    BBFURL = "https://www.broadband-forum.org/cwmp/" FileName
    FileName = <as before, except that BBFCorrigendum is modified as follows:>
    BBFCorrigendum = "-" NoLeadingZeroNumber
                   | ""         // if omitted, most recent corrigendum is assumed

For example, the DM Instance associated with TR-181 Issue 2 Amendment 11 can be accessed at https://www.broadband-forum.org/cwmp/tr-181-2-11-0.xml.

A.2.2 Descriptions

Many elements have descriptions, and the same rules apply to all description elements in the DM Schema. A description is free text which can contain a limited amount of MediaWiki-like markup as specified in A.2.2.3.

A.2.2.1 Character Set

Character set requirements apply to the entire DM Instance, so the contents of this section have been moved to C.2, which contains the normative requirements that apply to standard BBF DM Instances.

A.2.2.2 Pre-processing

All DM Instance processing tools MUST conceptually perform the following pre-processing before interpreting the markup:

1. Remove any leading whitespace up to and including the first line break. Note: It can be assumed that all line breaks are represented by a single line feed, i.e. ASCII 10. See C.2.

2. Remove the longest common whitespace prefix (i.e. that occurs at the start of every line) from each line. See the example below, where three lines start with four spaces and one line starts with five spaces, so the longest whitespace prefix that occurs at start of each line is four spaces. In this calculation, a tab character counts as a single character. To avoid confusion, the description SHOULD NOT contain tab characters.

3. Remove all trailing whitespace, including line breaks.

This pre-processing is designed to permit a reasonable variety of layout styles while still retaining predictable behavior. For example, both the following:

    <description>This is the first line.
    This is the second line.
     This is the indented third line.
    This is the fourth line.</description>

And:

    <description>
        This is the first line.
        This is the second line.
         This is the indented third line.
        This is the fourth line.
    </description>

…result in the following:

    This is the first line.
    This is the second line.
      This is the indented third line.
    This is the fourth line.

A.2.2.3 Markup

The pre-processed description can contain the following markup, which is inspired by, but is not identical to, MediaWiki markup. All DM Instance processing tools SHOULD support this markup to the best of their ability.

A.2.2.4 Templates

A template invocation is encoded as two curly braces on either side of the template name and arguments. Arguments can follow the template name, separated by vertical pipe (|) characters. All whitespace is significant. For example:

{{someTemplate|arg1|arg2|...|argN}}

In some cases, one template can impact the behavior of another template, e.g. the definitions of both the {{enum}} and the {{hidden}} templates state that the template expansion can be automatically placed after the rest of the description, which raises the question of which template expansion would come first. This ambiguity is resolved by stating that processing tools SHOULD generate such automatic text in the same order that the templates are defined below. In the above example, {{enum}} is defined before {{hidden}}, so an automatically-generated list of enumeration values would be placed before an automatically-generated explanation that the parameter value is hidden.

The following standard templates are defined. Any vendor-specific template names MUST obey the rules of Section 3.3.

A.2.2.5 HTML Example

This includes examples of most of the markup and templates.

    <model name="Goo:1.1" base="Goo:1.0">
      <object name="GooTop." access="readOnly" minEntries="1" maxEntries="1">
        <parameter name="ExampleParam" access="readOnly">
          <description>
    {{section|Introduction}}This is an ''example'' parameter that
    illustrates many of the '''formatting''' templates. For
    '''''example''''', this references {{bibref|TR-106a1|section 3.2}}.

    {{section|Usage}}This parameter is called {{object}}{{param}}. One can
    also reference other parameters in the same object, such as
    {{param|OtherParameter}}, and indicate that the parameter value is
    measured in {{units}}.

    One can also include bulleted lists:
    * level one
    ** level two
    * level one again
    ** level two again
    *** level three
    *: level one continued

    and numbered lists:
    # level one
    ## level two
    # level one again
    ## level two again
    ### level three
    #: level one continued

    and indented lists
    : level one
    :: level two
    : level one again
    :: level two again
    ::: level three

    and hyperlinks such as https://www.google.com

    and code examples:
     if (something) {
       /* do something */
     } else {
       /* do other */
     }

    If the parameter was Boolean, one could refer to its values {{false}}
    and {{true}}.

    One can refer to its enumerations individually, e.g. {{enum|Disabled}},
    or to other parameters' enumerations, such as {{enum|Value|OtherParam}},
    or can list them all. {{enum}}

    Finally, if there were any patterns they could be listed too. {{pattern}}
          </description>
          <syntax>
            <string>
              <enumeration value="A"/>
              <enumeration value="B"/>
              <units value="packets"/>
            </string>
          </syntax>
        </parameter>

The resulting HTML would look something like this:

A.2.3 Data Types

CWMP [1] and USP [13] data models support only the primitive data types listed in the last row of Table 3 “on the wire”. However, the DM Schema allows data types to be derived from the primitive types or from other named data types. Such derived types can be named or anonymous.

A.2.3.1 Named Data Types

Named data types are defined using the top-level dataType element. A DM Instance can contain zero or more top-level dataType elements.

When defining a new named data type, the following attributes and elements are relevant (normative requirements are specified in the schema).

For example:

    <dataType name="String255">
      <description>String of maximum length 255.</description>
      <string>
        <size maxLength="255"/>
      </string>
    </dataType>

    <dataType name="String127" base="String255">
      <description>String of maximum length 127.</description>
      <size maxLength="127"/>
    </dataType>

    <dataType name="String127List" base="String127">
      <description>List of up to 7 strings, each of maximum length 127. If a
      list item is itself a list, it will be "protected" by square
      brackets.</description>
      <list maxItems="7" nestedBrackets="required"/>
    </dataType>

A.2.3.2 Anonymous Data Types

Anonymous data types are defined within parameter syntax elements (A.2.7.1), and can apply only to the parameters within which they are defined. For example:

    <parameter name="Example1" access="readOnly">
      <syntax>
        <string>
          <size maxLength="127"/>
          </string>
      </syntax>
    </parameter>

    <parameter name="Example2" access="readOnly">
      <syntax>
        <dataType base="String255">
          <size maxLength="127"/>
        </dataType>
      </syntax>
    </parameter>

A.2.3.3 Data Type Facets

A facet specifies some aspect of a data type, e.g. its size, range or units.

Note that XML Schema [11] also associates facets with data types. The XML Schema and DM Schema concepts are the same, but the set of facets is not identical.

The DM Schema defines the following facets (normative requirements are specified in the schema):

It is important to note that the enumeration facet does not necessarily define all the valid values for a data type. This is for the following reasons:

• As specified in Section 3.3, vendors are allowed to add additional enumeration values.

• A future version of a data model may need to add additional enumeration values.

A.2.3.4 Reference Path Names

Some description templates (A.2.2.4), and all reference facets (A.2.3.7), need to specify parameter, command, event or object names. It is always possible to specify a full Path Name, but it is frequently necessary or convenient to specify a relative Path Name. For example, it might be necessary to reference another parameter in the current object. Any Instance Numbers in the parameter’s full Path Name cannot be known at data model definition time, so this can only be done using a relative Path Name.

The following rules apply to all Path Names that are used in data model definitions for referencing parameters or objects:

• Path Names MAY contain “{i}” placeholders, which MUST be interpreted as wild cards matching all Instance Numbers, e.g. “Device.Ethernet.Interface.{i}.” references all Ethernet.Interface instances.

• Path Names MUST NOT contain Instance Numbers.

A Path Name is always associated with a path name scope, which defines the point in the naming hierarchy relative to which the Path Name applies.

Formally, if the path name scope is normal:

• If the path is empty, it MUST be regarded as referring to the top of the naming hierarchy.

• Otherwise, if the path begins with a “Device” component, it MUST be regarded as a full Path Name.

• Otherwise, if the path begins with a dot (“.”), it MUST be regarded as a path relative to the Mount Point (if mounted) or to the Root or Service Object (otherwise). For example:

  • Device.LocalAgent.MTP.{i}.STOMP.Reference uses “.STOMP.Connection.” to reference the Device.STOMP.Connection. table, but if Device.LocalAgent was mounted at Device.ProxiedDevice.{i}. then Device.ProxiedDevice.{i}.LocalAgent.MTP.{i}.STOMP.Reference would reference the Device.ProxiedDevice.{i}.STOMP.Connection. table.

  • In the Device Root Object, “.DeviceInfo.” means Device.DeviceInfo., but in the Device.Services.ABCService.1 Service Object it means Device.Services.ABCService.1.DeviceInfo..

• Otherwise, it MUST be regarded as a path relative to the current object. Any leading hash characters (“#”) cause it to be relative to the parent of the current object (or the parent’s parent, and so on) as described below. For example:

  • If the current object is Device.LAN., “IPAddress” means Device.LAN.IPAddress, “Stats.” means Device.LAN.Stats. and “#.DeviceInfo.” means Device.DeviceInfo (see below for more “#” examples).

If the path name scope is model:

• If the path is empty, it MUST be regarded as referring to the Root or Service Object.

• Otherwise, it MUST be regarded as a path relative to the Root or Service Object. Any leading dot MUST be ignored. Leading hash characters are not permitted.

If the path name scope is object:

• If the path is empty, it MUST be regarded as referring to the current object.

• Otherwise, it MUST be regarded as a path relative to the current object. Any leading dot MUST be ignored. Leading hash characters are not permitted.

As mentioned above, if the path name scope is normal, a leading hash character causes the path to be relative to the parent of the current object. Additional hash characters reference the parent’s parent, and so on, but they MUST NOT be used to reference beyond the Root or Service Object. Also, for object instances, “#.” always means the Multi-Instance Object’s (table’s) parent rather than the Multi-Instance Object (table).

In addition, within a component definition, items that are defined outside the component MUST NOT be referenced via relative paths. This is because components can be included anywhere within the data model tree.

For example, if the current object is “Device.LAN.DHCPOption.{i}.”:

• “#.” means “Device.LAN.” (the table’s parent, not the table).

• “#.DHCPOption.” means “Device.LAN.DHCPOption.” (the table).

• “#.Stats.” means “Device.LAN.Stats.”.

• “#.Stats.TotalBytesSent” means “Device.LAN.Stats.TotalBytesSent”.

The following examples would be invalid if LAN was defined within a component:

• “##.” means “Device.”.

• “##.DeviceInfo.” means “Device.DeviceInfo.”.

• “##.DeviceInfo.Manufacturer” means “Device.DeviceInfo.Manufacturer”.

The final example can never be valid:

• “###.” is not permitted (references beyond the Root Object).

Note that the term “Root or Service Object”, which is used several times above, means “if within a Service Object instance, the Service Object instance; otherwise, the Root Object”.

For example, the pathRef and instanceRef facets (A.2.3.7) have a targetParent attribute which specifies the possible parent(s) of the referenced parameter or object, and a targetParentScope attribute (defaulted to normal) which specifies targetParent’s scope. If the current object is within a Service Object instance, setting targetParentScope to model forces the referenced parameter or object to be in the same Service Object instance. Similarly, setting targetParentScope to object forces the referenced parameter or object to be in the same object or in a sub-object.

A.2.3.5 Null Values and References

Each primitive data type has an associated null value that is used, for example, as the expansion of the {{null}} template (A.2.2.4). These null values are defined as follows:

• base64, hexBinary, string: an empty string

• unsignedInt, unsignedLong: 0

• int, long: -1

• boolean: false

• dateTime: 0001-01-01T00:00:00Z (the Unknown Time; see Section 3.2.1)

A null reference indicates that a reference parameter is not currently referencing anything. The value that indicates a null reference is the null value for the reference parameter’s base data type, i.e.:

• string: an empty string

• unsignedInt: 0

• int: -1

A.2.3.6 Reference Types

A reference to another parameter or object can be weak or strong:

• weak: it does not necessarily reference an existing parameter or object. For example, if the referenced parameter or object is deleted, the value of the reference parameter might not get updated. All weak reference parameters MUST be declared as writable.

• strong: it always either references a valid parameter or object, or else is a null reference (A.2.3.5). If the referenced parameter or object is deleted, the value of the reference parameter is always set to a null reference.

See Section 3.2.3 for normative requirements relating to reference types and the associated Agent behavior.

A.2.3.7 Reference Facets

A reference facet specifies how a parameter can reference another parameter or object. There are three sorts of reference:

• Path reference: references another parameter or object via its Path Name. Details are specified via the pathRef facet, which applies to string and its derived types.

• Instance reference: references an object instance (table row) via its Instance Number. Details are specified via the instanceRef facet, which applies to int, unsignedInt and their derived types.

• Enumeration reference: references a list-valued parameter via its Path Name. The current value of the referenced parameter indicates the valid enumerations for this parameter. Details are specified via the enumerationRef facet, which applies to string and its derived types.

When defining a path reference, the following attributes and elements are relevant (normative requirements are specified in the schema).

When defining an instance reference, the following attributes and elements are relevant (normative requirements are specified in the schema).

When defining an enumeration reference, the following attributes and elements are relevant (normative requirements are specified in the schema).

The following examples illustrate the various possible types of reference.

    <object name="PeriodicStatistics.SampleSet.{i}.Parameter.{i}." ...>
      ...
      <parameter name="Reference" access="readWrite">
        <description>Reference to the parameter that is associated with this
        object instance. This MUST be the parameter's full path name.</description>
        <syntax>
          <string>
            <size maxLength="256"/>
            <pathRef targetType="parameter" refType="weak"/>
          </string>
          <default type="object" value=""/>
        </syntax>
      </parameter>

    <object name="StorageService.{i}.StorageArray.{i}." ...>
      ...
      <parameter name="PhysicalMediumReference" access="readWrite">
        <description>A comma-separated list of Physical Medium references.
        Each Physical Medium referenced by this parameter MUST exist within the
        same StorageService instance. A Physical Medium MUST only be referenced
        by one Storage Array instance. Each reference can be either in the form
        of ".PhysicalMedium.{i}" or a fully qualified object
        name...</description>
        <syntax>
          <list>
            <size maxLength="1024"/>
          </list>
          <string>
            <pathRef targetParent=".PhysicalMedium." targetParentScope="model"
            targetType="row" refType="strong"/>
          </string>
        </syntax>
      </parameter>

    <object name="STBService.{i}.Components.FrontEnd.{i}.IP.Inbound.{i}." ...>
      ...
      <parameter name="StreamingControlProtocol" access="readOnly">
        <description>Network protocol currently used for controlling streaming
        of the source content, or an empty string if the content is not being
        streamed or is being streamed but is not being controlled. If non-empty,
        the string MUST be one of the .Capabilities.FrontEnd.IP.StreamingControlProtocols
        values.</description>
        <syntax>
          <string>
            <enumerationRef
            targetParam=".Capabilities.FrontEnd.IP.StreamingControlProtocols"
            nullValue=""/>
          </string>
        </syntax>
      </parameter>

      <parameter name="StreamingTransportProtocol" access="readOnly">
        <description>Network protocol currently used for streaming the source
        content, or an empty string if the content is not being streamed.
        If non-empty, the string MUST be one of the
        .Capabilities.FrontEnd.IP.StreamingTransportProtocols
        values.</description>
        <syntax>
          <string>
            <enumerationRef
            targetParam=".Capabilities.FrontEnd.IP.StreamingTransportProtocols"
            nullValue=""/>
          </string>
        </syntax>
      </parameter>

    <object name="Device.WiFi.AccessPoint.{i}.Security." ...>
      ...
      <parameter name="ModeEnabled" access="readWrite">
        <description>Indicates which security mode is enabled.</description>
        <syntax>
          <list/>
          <string>
            <enumerationRef targetParam="ModesSupported"/>
          </string>
        </syntax>
      </parameter>

A.2.3.8 Base Type Restriction

A new data type MUST always be a restriction of its base type, meaning that a valid value of the new data type will always be a valid value for its base type. This is the case for the examples of A.2.3.1, which involve three different data types:

• string of unlimited length

• string of maximum length 255

• string of maximum length 127

Clearly a string of length 100 is valid for all three data types, but a string of length 200 is only valid for the first two data types.

The examples of A.2.3.1 considered only the size facet, but in general all facets that are applicable to the data type have to be considered. The base type restriction requirements for each facet are as follows:

Most of the above requirements are non-normative, because it has to be possible to correct errors. For example, if the base type supports a range of [-1:4095] but the values 0 and 4095 were included in error, it would be permissible for a derived type to support ranges of [-1:-1] and [1:4094]. Processing tools SHOULD be able to detect and warn about such cases.

When defining a new data type, if a facet is omitted, the new data type will inherit that facet from its base type. If a facet is present, it MUST be fully specified (except that special rules apply to descriptions; see below and A.2.12.6). For example, this means that a derived type that adds additional enumeration values has also to re-declare the enumeration values of the base type.

In the following example, the derived type inherits the units facet from its parent but it does not inherit the range facet, so the DataBlockSize range is [0:65535] and the DataBlockSize2 range is [40:1460].

   <dataType name="DataBlockSize">
     <unsignedInt>
       <range maxInclusive="65535"/>
       <units value="bytes"/>
     </unsignedInt>
   </dataType>

   <dataType name="DataBlockSize2" base="DataBlockSize">
     <range minInclusive="40" maxInclusive="1460"/>
   </dataType>

Similarly, in the following, the enumeration values for ABCD are not A, B, C and D, but are just C and D. This is an error (because the derived type cannot remove enumeration values), and processing tools SHOULD detect and warn about such cases.

    <dataType name="AB">
      <string>
        <enumeration value="A"/>
        <enumeration value="B"/>
      </string>
    </dataType>

    <dataType name="ABCD" base="AB">
      <string>
        <enumeration value="C"/>
        <enumeration value="D"/>
      </string>
    </dataType>

A derived data type and any of its facets that support descriptions will inherit those descriptions from the base type. Facet descriptions are inherited regardless of whether the facet is present in the derived type. For any descriptions that are explicitly specified in the derived type, the action attribute controls whether they will be prefixed, extended or replaced (A.2.12.6).

For example, in the following, the description of Z (which is not changed) does not have to be repeated.

    <dataType name="XY">
      <description>This is XY.</description>
      <string>
        <enumeration value="X">
          <description>This is X.</description>
        </enumeration>
        <enumeration value="Y">
          <description>This is Y.</description>
        </enumeration>
        <enumeration value="Z">
          <description>This is Z.</description>
        </enumeration>
      </string>
    </dataType>

    <dataType name="XY2" base="XY">
      <description action="replace">This is all about XY.</description>
      <enumeration value="X">
        <description action="append">This is more about X, added at the
        end.</description>
      </enumeration>
      <enumeration value="Y">
        <description action="prefix">This is more about Y, inserted at the
        beginning.</description>
      </enumeration>
      <enumeration value="Z"/>
    </dataType>

A.2.4 Glossary, Abbreviations, Bibliography and Templates

A.2.4.1 Glossary

The glossary is defined using the top-level glossary element, which can contain zero or more item elements.

When defining a new glossary item, the following attributes and elements are relevant (normative requirements are specified in the schema).

A.2.4.2 Abbreviations

Abbreviations are defined using the top-level abbreviations element, which can contain zero or more item elements.

When defining a new abbreviation, the following attributes and elements are relevant (normative requirements are specified in the schema).

A.2.4.3 Bibliography

The bibliography is defined using the top-level bibliography element, which can contain zero or more (bibliographic) reference elements.

When defining a new bibliographic reference, the following attributes and elements are relevant (normative requirements are specified in the schema).

For BBF standard DM Instances, the C.3.7 rules apply.

Processing tools SHOULD be lenient when comparing bibliographic reference IDs. Specifically, they SHOULD ignore all whitespace, punctuation, leading zeros in numbers, and upper / lower case. So, for example, “rfc 1234” and “RFC1234” would be regarded as the same ID, as would “TR-069” and “TR69”.

Processing tools SHOULD detect and report inconsistent bibliographic references, e.g. a reference with the same ID (i.e. an ID that compares as equal) as one that was encountered in a different file, but with a different name or hyperlink.

A.2.4.4 Templates

Template elements define named blocks of text that can be included (using {{template}} description templates) in descriptions.

When defining a new template element, the following attributes and elements are relevant (normative requirements are specified in the schema).

When including a template body in a description, processing tools MUST pre-process the value as for descriptions (A.2.2.2) and then replace the {{template}} description template with the resulting text. The template body might contain markup, possibly including further {{template}} description templates, so processing tools MUST then process the expanded text.

A.2.5 Components

A component is a way of defining a named set of parameters, objects and/or profiles to be used wherever such a group is needed in more than one place (or just to structure the definitions). A DM Instance can contain zero or more top-level component elements.

When defining a new component, the following attributes and elements are relevant (normative requirements are specified in the schema).

Referencing (including) a component can be thought of as textual substitution. A component has no version number and is not tied to a particular Root or Service Object.

The following is a simple example of component definition and reference.

    <component name="ByteStats">
      <parameter name="BytesSent" access="readOnly">
        <description>Number of bytes sent.</description>
        <syntax><unsignedInt/></syntax>
      </parameter>
      <parameter name="BytesReceived" access="readOnly">
        <description>Number of bytes received.</description>
        <syntax><unsignedInt/></syntax>
      </parameter>
    </component>

    <model name="Device:2.11">
      <object name="Device." access="readOnly" minEntries="1"
      maxEntries="1">
        ...
        <component ref="ByteStats"/>
        ...
      </object>
      ...
    </model>

Here the component is referenced from within an object definition. Components can be referenced from within component, model, object, command and event definitions. Parameter, command, event, object and profile definitions within components are relative to the point of inclusion unless overridden using the path attribute.

A.2.6 Root and Service Objects

Root and Service Objects are defined using the model element and an associated top-level object element. A DM Instance can contain zero or more top-level model elements.

When defining a new model, the following attributes and elements are relevant (normative requirements are specified in the schema).

Once a given version has been defined, it cannot be modified; instead, a new version of the object has to be defined. For example, the following example defines v1.0 and v1.1 of a notional Service Object.

    <model name="DemoService:1.0" isService="true">
      <parameter name="DemoServiceNumberOfEntries" access="readOnly"/>
      <object name="DemoService.{i}." access="readOnly" minEntries="0"
      maxEntries="unbounded" entriesParameter="DemoServiceNumberOfEntries"/>
    </model>

    <model name="DemoService:1.1" base="DemoService:1.0"
    isService="true">
      <object base="DemoService.{i}." access="readOnly" minEntries="0"
      maxEntries="unbounded"/>
    </model>

A.2.7 Parameters

Parameters are defined using the parameter element, which can occur within component, model and object elements. When defining a new parameter, the following attributes and elements are relevant (normative requirements are specified in the schema).

A.2.7.1 Parameter Syntax

Parameter syntax is defined using the syntax element, which can occur only within parameter elements. When defining a new parameter, the following attributes and elements are relevant (normative requirements are specified in the schema).

A.2.8 Commands (USP Only)

Data Model Commands are defined using the command element, which can occur within component and object elements. When defining a new Data Model Command, the following attributes and elements are relevant (normative requirements are specified in the schema). This concept does not apply to CWMP, which uses Objects and/or Parameters to simulate commands.

The input / output elements define the command’s input / output arguments (respectively).

Command argument parameter / object elements are similar to the corresponding data model parameter / object elements but support different attributes, e.g. they have no access or numEntriesParameter attributes, and they have a Boolean mandatory attribute (to indicate a mandatory argument).

When a command references a component, any attributes not supported in command arguments are ignored. This allows a component that defines data model parameters / objects to be used for defining command parameter / object arguments.

When a command argument is a table, its instance numbers MUST be 1, 2, 3… (assigned sequentially without gaps).

A.2.9 Events (USP Only)

Data Model Events are defined using the event element, which can occur within component and object elements. When defining a new Data Model Event, the following attributes and elements are relevant (normative requirements are specified in the schema). This concept does not apply to CWMP.

Event argument parameter / object elements are similar to the corresponding data model parameter / object elements but support different attributes, e.g. they have no access or numEntriesParameter attributes, and they have a Boolean mandatory attribute (to indicate a mandatory argument).

When an event references a component, any attributes not supported in event arguments are ignored. This allows a component that defines data model parameters / objects to be used for defining event parameter / object arguments.

When an event argument is a table, its instance numbers MUST be 1, 2, 3… (assigned sequentially without gaps).

A.2.10 Objects

Objects are defined using the object element, which can occur within component and model elements. When defining a new object, the following attributes and elements are relevant (normative requirements are specified in the schema).

A.2.10.1 Tables

If an object is a table, several other attributes and elements are relevant (normative requirements are specified in the schema).

Each unique key is either functional or non-functional:

• A functional key references at least one parameter that is necessary for the correct operation of the table, e.g., a DHCP option tag in a DHCP option table, or an external port number in a port mapping table.

• A non-functional key references only parameters that are not necessary for the correct operation of the table, e.g., an Alias parameter or (sometimes) a Name parameter.

A unique key is assumed to be functional unless explicitly marked as non-functional by setting the unique key’s functional attribute to false.

As can be seen from the description in Table 21, in CWMP, non-functional keys are always required to be unique, regardless of whether the table has an enableParameter, or is enabled or disabled. Therefore, at most one entry in a given parent object can exist with a given value for a non-functional unique key. USP doesn’t require any different behavior for both functional and non-functional keys: all keys are always required to be unique.

The uniqueness requirement means that the value of the unique key MUST be unique for all instances of a given parent object regardless of how instances got created.

If a parameter (or group of parameters) is not defined as a unique key, an Agent MUST NOT expect or require those parameters to contain a value that is unique within the table. Such parameters MAY subsequently be defined as a vendor-specific data model composite unique key, but that composite unique key definition MUST include at least one vendor-specific parameter.

A.2.11 Profiles

Profiles are defined using the profile element, which can occur within component and model elements. When defining a new profile, the following attributes and elements are always relevant (normative requirements are specified in the schema).

Note:

• If a command or event specifies no argument requirements, this is the same as if all of its mandatory arguments were listed.

• If a command or event specifies argument requirements, it has to list (at least) all its mandatory arguments.

A.2.12 Modifications

As experience is gained with a data model, it may be desirable to revise that model. However, changes to published models are not allowed if they have any potential to cause interoperability problems between a Controller using an original specification and an Agent using an updated specification.

New data types, components, models and profiles can be created based on existing items. This does not modify the existing item.

Parameters, commands, events, objects and profiles can be modified “in place”, i.e. without creating a new item. This still uses the parameter, command, event, object and profile elements, and is indicated by using the base, rather than the name, attribute. The base attribute specifies the name of the existing item that is to be modified.

The syntax for modifying an item is the same as for creating an item, but there are rules. These rules are not specified in the DM Schema.

A.2.12.1 Parameter Modifications

The following rules govern parameter modifications.

Most of the above requirements are non-normative, because it has to be possible to correct errors in a previous version of a parameter. Processing tools SHOULD be able to detect and warn when a parameter is modified in a way that contravenes the above rules.

A.2.12.2 Command Modifications (USP Only)

The following rules govern command modifications.

Most of the above requirements are non-normative, because it has to be possible to correct errors in a previous version of a parameter. Processing tools SHOULD be able to detect and warn when a parameter is modified in a way that contravenes the above rules.

A.2.12.3 Event Modifications (USP Only)

The following rules govern command modifications.

Most of the above requirements are non-normative, because it has to be possible to correct errors in a previous version of a parameter. Processing tools SHOULD be able to detect and warn when a parameter is modified in a way that contravenes the above rules.

A.2.12.4 Object Modifications

The following rules govern object modifications.

Most of the above requirements are non-normative, because it has to be possible to correct errors in a previous version of an object. Processing tools SHOULD be able to detect and warn when an object is modified in a way that contravenes the above rules.

A.2.12.5 Profile Modifications

The following rules govern profile modifications. They apply to the profile element, and to its nested parameter, command, event and object elements.

Most of the above requirements are non-normative, because it has to be possible to correct errors in a profile. Indeed, since profiles are immutable, the only valid reason for changing a profile is to correct errors. Processing tools SHOULD be able to detect and warn when a profile is modified in a way that contravenes the above rules.

A.2.12.6 Description Modifications

The following rules govern description modifications. They apply to all description elements.

In the case of prefix and append, processing tools SHOULD insert a line break between the existing description and the new text.

A.2.13 Versions

Section 2.2 explains how Root and Service Object versions are specified, and Section 2.3.3 explains how Profile versions are specified. In brief:

• Root and Service Object versions are specified via the model element’s name attribute (A.2.6)
• Profile versions are specified via the profile element’s name attribute (A.2.11)

For example, this defines version 2.0 of the Device Root Object and version 1 of its Baseline profile.

<model name="Device:2.0">
  <object name="Device.">
    ...
  </object>
  <profile name="Baseline:1">
    ...
  </profile>
</model>

The version attribute specifies the data model version (of the form m.n or m.n.p) in which a given item was first defined. It is mandatory in the following cases:

• On model definitions when the corrigendum number (p) is greater than zero (because the model element’s name attribute can’t indicate an m.n.p version)
• On all object and profile definitions (this is checked by schema validation)
• On all other item definitions (parameters, enumerations, patterns, commands, events, arguments) that were defined in a later version than their parent

The version attribute is sometimes needed in the following case:

• On a component reference, in which case it’s a “clamp version”, which means that any component item versions less than the clamp version are set to the clamp version

The version attribute is forbidden in the following cases:

• On item definitions (other than objects and profiles) that were defined in the same version as their parent
• When using the base attribute to modify an existing definition (this is checked by schema validation)

These rules mean that the earlier example was in fact invalid due to missing object and profile version attributes. This extended example fixes the problems.

<model name="Device:2.1">
  <object name="Device." version="2.0">
    ...
    <command name="Reboot()" version="2.1">
      ...
    </command>
    <event name="Boot!">
      ...
    </event>
  </object>
  <profile name="Baseline:1" version="2.0">
    ...
  </profile>
  <profile name="Baseline:2" base="Baseline:1" version="2.1">
    ...
  </profile>
</model>

A.3 DM Schema

The normative version of the DM Schema can be found at https://www.broadband-forum.org/cwmp-datamodel-schema. Please be aware that a new version of the DM Schema might be published at any time, in which case the version referenced in this document would become out of date. Any conflict MUST be resolved in favor of the normative version on the web site.

A.4 DMR Schema

The DMR Schema is a non-normative XML Schema that can be used to give hints to processing tools that generate reports from DM Instances.

The DMR Schema can be found at https://www.broadband-forum.org/cwmp-datamodel-report-schema. It’s usually used as follows, with a dmr (“Data Model Report”) prefix.

<dm:document
    xmlns:dmr="urn:broadband-forum-org:cwmp:datamodel-report-1-0"
    xsi:schemaLocation="
      urn:broadband-forum-org:cwmp:datamodel-report-1-0
      https://www.broadband-forum.org/cwmp/cwmp-datamodel-report-1-0.xsd">

Most DMR attributes are booleans, for which a true value enables some special behavior.

Annex B: CWMP Device Type XML Schema

• B.1 Introduction
• B.2 Normative Information
  • B.2.1 Importing DM Instances
  • B.2.2 Features
• B.3 DT Schema

B.1 Introduction

The CWMP Device Type XML Schema [11], or DT Schema, is used for describing a device’s supported data model.

DT Schema instance documents can contain the following:

• Imports (from DM Schema instance documents) of Root or Service Object definitions

• Declarations of which features of imported Root or Service Objects are supported

DT Schema instance documents cannot contain definitions of Root or Service Objects. All such definitions have to reside in DM Schema instance documents.

B.2 Normative Information

It is possible to create instance documents that conform to the DT Schema but nevertheless are not valid device type specifications. This is because it is not possible to specify all the normative device type specification requirements using the XML Schema language. Therefore, the schema contains additional requirements written using the usual normative language. Instance documents that conform to the DT Schema and meet these additional requirements are referred to as DT Instances.

The question of the location of the definitive normative information therefore arises. The answer is as follows:

• All the normative information in the main part of the document remains normative.

• The DT Schema, and the additional requirements therein, are normative. Some of these additional requirements are duplicated (for emphasis) in this Annex.

• The DT Schema references additional material in this Annex. Such material is normative.

• If the DT Schema conflicts with a normative requirement in the main part of the document, this is an error in the DT Schema, and the requirement in the main part of the document takes precedence.

B.2.1 Importing DM Instances

DM Instances are imported using the top-level import element, which differs from the DM Schema import element in that only data types and models can be imported (components cannot be imported because they are not used in DT Instances).

Note – the rules for importing DM Instances into DT Instances are consistent with those given in A.2.1 for importing DM Instances into other DM Instances. The only difference is an additional rule governing the use, when available, of the DT Instance URL.

The DT Schema specifies that the DM Instance is located via the file attribute.

The rules governing the file attribute’s value and its use for locating the DM Instance are as follows:

• It MUST be a URL adhering to RFC 3986 [8].

• If the URL includes a scheme, it MUST be http, https or ftp.

• If the URL includes an authority, it MUST NOT include credentials.

• For standard BBF DM Instances, the rules that apply to the filename part (final path segment) of the A.2.1.1 BBFURL MUST be applied to the filename part of this URL. This means that the corrigendum number can be omitted in order to refer to the latest corrigendum.

• If the URL is a relative reference, processing tools MUST apply their own logic, e.g. apply a search path. If a DT Instance URL is available, the relative reference MUST be interpreted relative to the DT Instance URL.

B.2.2 Features

The feature element provides a simple way for a DT Instance to indicate whether a given feature is supported. The current set of standard features is as follows:

Vendor-specific features MAY be supported, and if so the feature name MUST begin with X_<VENDOR>_, where <VENDOR> MUST be as defined in Section 3.3.

This example feature declaration illustrates the use of annotation:

    <feature name="DNSServer">
      <annotation>Supports a DNS Server and XYZ.</annotation>
    </feature>

B.2.2.1 DT Features Schema

In order to make it easy to add new features, standard feature names are defined in a separate DT Features Schema that is imported by the DT Schema. The DT Features Schema is unversioned, so the DT Schema need not be changed when new standard feature names are added. In order to preserve backwards compatibility, standard feature names, once added, MUST NOT ever be deleted.

The normative version of the DT Features Schema can be found at https://www.broadband-forum.org/cwmp-devicetype-features-schema. Please be aware that a new version of the DT Features Schema might be published at any time, in which case the version referenced in this document would become out of date. Any conflict MUST be resolved in favor of the normative version on the web site.

B.3 DT Schema

The normative version of the DT Schema can be found at https://www.broadband-forum.org/cwmp-devicetype-schema. Please be aware that a new version of the DT Schema might be published at any time, in which case the version referenced in this document would become out of date. Any conflict MUST be resolved in favor of the normative version on the web site.

Annex C: Requirements for BBF Standard Data Models

• C.1 Introduction
• C.2 Character Encoding and Character Set
• C.3 XML Usage
  • C.3.1 Data Model Item Names
  • C.3.2 DM and DMR Schema Versions
  • C.3.3 SchemaLocation Attribute
  • C.3.4 Spec Attribute
  • C.3.5 File Attribute
  • C.3.6 Import Element
  • C.3.7 Bibliography Reference Element
  • C.3.8 General Formatting
• C.4 Initial XML Comment Formatting
  • C.4.1 One-line Summary
  • C.4.2 Summary Section

C.1 Introduction

This Annex defines requirements that apply to all standard BBF DM Instances. These requirements extend the normative requirements of the DM Schema (Annex A).

C.2 Character Encoding and Character Set

The file MUST use UTF-8 encoding, indicated by the following Initial line:

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

The file MUST use only a subset of the printable characters in the Basic Latin Unicode block, namely characters whose decimal ASCII representation is 10 (#xA), 13 (#xD) or is in the (inclusive) range 32-126.

Note – writing LF (LINE FEED) for #xA and CR (CARRIAGE RETURN) for #xD, the XML specification [9, section 2.11] states that XML processors have to behave as if all CR LF sequences, or any CR characters not followed by LF, are translated to LF.

Note – TAB (#x9) is not permitted. This is because no standard indentation level is defined for TAB characters, so the indentation is ambiguous when there is a mixture of SPACE (#x20) and TAB characters.

Note – it is not permissible to include a non-printable ASCII character by using a character reference such as “è”. Such a character reference will always be replaced with the referenced character before being passed to the application, so use of the reference is no different from direct use of the referenced character (in this case the letter “è”, an “e” with a grave accent).

C.3 XML Usage

C.3.1 Data Model Item Names

All data model item names, i.e. data type, component, data model, object, parameter and profile names, MUST start with an upper-case letter (or an underscore for an internal data type, component, model or profile) and MUST NOT contain hyphens or non-initial underscores.

C.3.2 DM and DMR Schema Versions

The file SHOULD use the most recent approved versions of the DM Schema (A.3) and the DMR Schema (A.4).

C.3.3 SchemaLocation Attribute

The top-level xsi:schemaLocation attribute defines the location of all of the referenced BBF-published XML Schemas. All URLs MUST be absolute ones that reference the published XML Schema on the BBF web site.

Example:

    xsi:schemaLocation="urn:broadband-forum-org:cwmp:datamodel-1-5
                          https://www.broadband-forum.org/cwmp/cwmp-datamodel-1-5.xsd
                        urn:broadband-forum-org:cwmp:datamodel-report-0-1
                          https://www.broadband-forum.org/cwmp/cwmp-datamodel-report.xsd"

C.3.4 Spec Attribute

The top-level spec attribute (A.2.1.1) indicates the specification with which the file is associated. It MUST be of the form “urn:broadband-forum-org:tr-nnn-i-a-c”, where nnn is the specification number (including leading zeros), i is the issue number, a is the amendment number, and c is the corrigendum number. The issue, amendment and corrigendum numbers do not include leading zeros. For example, “urn:broadband-forum-org:tr-106-1-0-0” refers to TR-106 (Issue 1 Amendment 0), and “urn:broadband-forum-org:tr-106-1-2-1” refers to TR-106 (Issue 1) Amendment 2 Corrigendum 1.

Example:

    spec="urn:broadband-forum-org:tr-181-2-5-0"

C.3.5 File Attribute

The top-level file attribute (A.2.1.1) indicates the file name. It MUST be of the form “tr-nnn-i-a-c.xml” or “tr-nnn-i-a-c-label.xml”, where nnn, i, a and c are the same as in the spec attribute. The label, which MUST NOT begin with a digit, is only needed if more than one DM Instance is associated with a given specification.

Example:

    file="tr-181-2-5-0.xml"

C.3.6 Import Element

The import element’s spec and file attributes MUST NOT specify the corrigendum number. This means that an import element always references the latest corrigendum (A.2.1.1).

C.3.7 Bibliography Reference Element

The bibliography reference id attribute is intended to uniquely identify this reference across all instance documents. Therefore, this attribute MUST obey the following rules:

For a BBF Technical Report, it MUST be of the form “TR-nnnixaycz”, where TR is the literal “TR”, nnn is the Technical Report number (including leading zeros), i, a and c are literal letters, and x, y, and z are the issue, amendment and corrigendum numbers (respectively). Omitted issue, amendment or corrigendum numbers refer to the most recent issue, amendment or corrigendum, so “TR-nnn” is the most recent corrigendum of the most recent amendment of the most recent issue, “TR-nnni2” is the most recent corrigendum of the most recent amendment of issue 2, etc.. Literal i1, a0 and/or c0 can be used, if needed, to refer specifically to the initial version.

For an IETF RFC, it MUST be of the form “RFCnnn”, where RFC is the literal “RFC” and nnn is the RFC number (no leading zeros).

For an IEEE specification, it SHOULD be of the form “nnn.ml-dddd”, where nnn.m is the IEEE group, l is the spec letter(s), and dddd is the publication year. For example, “802.1D-2004”.

For an ETSI specification (which includes DVB specifications), it SHOULD be of the form “TTnnnnnnva.b.c” where TT is the specification type, usually “TS” (Technical Specification), nnnnnn is the specification number, and a.b.c is the version number.

For specifications issued by other standards organizations, or by vendors, it SHOULD be of a standard form if one is defined.

Formally, bibliographic reference IDs in instance documents that are published by the BBF and the other organizations mentioned above are defined as follows:

    ReferenceID = BBFID
                | RFCID
                | IEEEID
                | ETSIID
                | OtherID

    BBFID = "TR-" BBFNumber BBFIssue BBFAmendment BBFCorrigendum

    BBFNumber = DIGIT{3,} // including leading zeros, e.g. 069

    BBFIssue = "i" <number greater than one>
             | "" // empty means the most recent Issue

    BBFAmendment = "a" <number greater than zero>
                 | "" // empty means the most recent Amendment

    BBFCorrigendum = "c" <number greater than zero>
                   | "" // empty means the most recent Corrigendum

    RFCID = "RFC" RFCNumber

    RFCNumber = NONZERODIGIT [DIGIT]*
                              // no leading zeros, e.g. 123

    IEEEID = IEEEGroup IEEESpec IEEEDate
           | <for other IEEE specifications, of a standard form if one is defined>

    IEEEGroup = <group number> "." <group sub-number>
                                // e.g. 802.1

    IEEESpec = <spec letter(s)> // e.g. D

    IEEEDate = "-" <publication year>
                                // e.g. -2004
             | ""               // can be empty

    ETSIID = ETSISpecType ETSINumber ETSIVersion
           | <for other ETSI specifications, of a standard form if one is defined>

    ETSISpecType = "TR" // Technical Report
                 | "TS" // Technical Specification
                 | "ES" // ETSI Specification
                 | "EN" // European Standard

    ETSINumber = [DIGIT]{6} // e.g. 102034

    ETSIVersion = "v" <version number as specified by ETSI>
                | ""            // can be empty

    OtherURI = <of a standard form if one is defined>

C.3.8 General Formatting

The file MUST use 2 SPACE characters for indentation.

The file MUST be consistently indented, including within XML comments.

XML comment lines SHOULD NOT be longer than 79 characters. This avoids line wrap in most text editors.

All description elements MUST be formatted as follows:

• Single-line descriptions MAY be indented and formatted on separate lines (as for multi-line descriptions) or inline, as in:

  <description>One line description.</description>

• Multi-line descriptions MUST be indented relative to the description element and formatted on separate lines, as in:

    <description>
      First line of multi-line description.
      Second line of multi-line description.
    </description>

C.4 Initial XML Comment Formatting

The Initial Line (the <?xml> line) MUST be immediately followed by an Initial XML comment that consists of the following (separated by blank lines):

• One-line summary.

• Notice section.

• Summary section.

• Issue History section.

The three sections MUST be introduced by a line that consists of two SPACE characters followed by the section name and a colon.

    <?xml version="1.0" encoding="UTF-8"?>
    <!--
      ...One-line summary...

    Notice:
      ...standard notice...

    Summary:
      ...multi-line summary...

    Issue History:
      ...summary of changes in each approved version...

    -->

C.4.1 One-line Summary

The One-line summary MUST contain a brief description of the reason for the creation of this version. It SHOULD NOT be terminated with a period (it is not a sentence).

Example:

    <?xml version="1.0" encoding="UTF-8"?>
    <!-- Added support for IPsec -->

C.4.2 Summary Section

The Summary section MAY extend the information in the One-line summary.