Annex C: Requirements for BBF Standard Data Models

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 [Section 2.11/8] 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 “&#xe8;”. 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 and DMR Schemas.

Note – 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.

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
                          http://www.broadband-forum.org/cwmp/cwmp-datamodel-1-5.xsd
                        urn:broadband-forum-org:cwmp:datamodel-report-0-1
                          http://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

Bibliographic references in the tr-069-biblio.xml file MUST be grouped by organization and MUST be sorted “naturally” (more-or-less alphabetically, but avoiding surprises, e.g., “TR-181a9” would be listed before “TR-181a10”). The main rule is “follow existing practice”.

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.

When using the {{bibref}} template to refer to bibliographic references, the plain “TR-nnn” form SHOULD be used by default; more specific forms can be used where the reference is to a specific 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:

    <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):

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.