BIBLIOGRAPHY - TR-154 TR-069 Data Model XML User Guide

Bibliography references are defined using the bibliography/reference element (I.5.1). There are two ways to define bibliography references:

within the central bibliography file, or within a given Data Model file

Regardless of where a bibliography reference is defined, it can be cited from within descriptions in the same manner.

Note – Defining references within the central bibliography file means that they can be reused across Data Models.

Note – The DM Schema indicates that bibliographies are defined under a document element, which means that they can be defined within any XML file. This might be useful when a draft document is in development. However, the convention is to limit bibliography definitions to the central bibliography file for all published documents.

6.1.1 Adding Reusable Bibliography Reference Elements

The centralized, global bibliography is defined in tr-069-biblio.xml. This file lists both Broadband Forum and external specifications that are cited in the various XML Data Models. It most cases, it is best to use this central file to define bibliography reference elements.

The following listing illustrates the layout and key elements found in tr-069-biblio.xml (see I.5 for details on the bibliography element). Two bibliography references are defined in this example, RFC 4122 and TR-181i2a1.

spec="urn:broadband-forum-org:tr-069-biblio"> <bibliography>

...

<title>A Universally Unique Identifier (UUID) URN Namespace</title> <organization>IETF</organization> <category>RFC</category> <date>2005</date> <hyperlink>http://tools.ietf.org/rfc/rfc4122.txt</hyperlink> </reference> ... <reference id="TR-181i2a1">

<name>TR-181 Issue 2 Amendment 1</name> <title>Device Data Model for TR-069</title> <organization>Broadband Forum</organization> <category>TR</category> <date>2010</date> </reference> ... <bibliography> </dm:document>

To add a new bibliography reference to tr-069-biblio.xml, simply insert a bibliography/- reference element and its related sub-elements. At a minimum, the reference needs to include an id, name, title, and should also include organization, category, date, and hyperlink where applicable. Broadband Forum bibliography references do not need to include a hyperlink to the published specification, since this information is well-known and can be generated by the Report Tool.

The id is intended to uniquely identify a bibliography reference across all DM Instance documents (i.e. it should be globally unique). Appendix A.2.4/TR-106 [3] specifies a set of rules used to determine the standard id value for specifications published by various SDOs. These

rules can be summarized through example9:

“TR-181” refers to BBF technical report TR-181 Issue 1 (Amendment 0)

“TR-106a2” refers to BBF technical report TR-106 Issue 1 Amendment 2

“TR-181i2a1” refers to BBF technical report TR-181 Issue 2 Amendment 1

“RFC4078” refers to IETF RFC 4078

“802.1D-2004” refers to IEEE 802.1D-2004

“G.998.3” refers to ITU-T G.998.3

This id is used by XML Data Models in order to cite specific references from within description elements.

Note – A Data Model file will need to import tr-069-biblio.xml in order to use its bibliography. 6.1.2 Adding Data-Model Specific Bibliography Reference Elements

Defining bibliography references from within a given Data Model file is accomplished in much the same way as is done using tr-069-biblio.xml (see 6.1.1). Although extending tr-069- biblio.xml is preferred, if the reference is highly specific to the Data Model in question then it

An id value will not contain space characters. An id value for a Broadband Forum technical report will not include the corrigendum; the latest corrigendum is always assumed.

can be defined directly within the Data Model file. But doing this means that this bibliography reference cannot be reused by other (unrelated) Data Models.

The following listing illustrates the definition a bibliography reference from within a Data Model file (see I.5 for details on the bibliography element).

<dm:document xmlns:dm="urn:broadband-forum-org:cwmp:datamodel-1-3" ... spec="urn:broadband-forum-org:tr-135-1-1-0">

...

<import file="tr-069-biblio.xml" spec="urn:broadband-forum-org:tr-069-biblio"/> ...

<bibliography> ...

<title>The TV-Anytime Content Reference Identifier (CRID)</title> <organization>IETF</organization> <category>RFC</category> <hyperlink>http://www.ietf.org/rfc/rfc4078.txt</hyperlink> </reference> ... <bibliography> <model...> ... </model> </dm:document>

A new bibliography reference is defined within the document using a bibliography/- reference element. This is exactly the same as in the tr-069-biblio.xml file.

The bibliography element comes after the description and import elements (if present), and before other top-level elements such as model and component.

Note – In the above listing, importing tr-069-biblio.xml is optional. Doing so is only necessary if the Data Model cites references defined in that file.

Note – Be careful not to duplicate references already defined within the central tr-069-biblio.xml file. The Report Tool includes a warnbibref setting to warn against such duplications (see V.4.1).

6.1.3 Citing a Bibliographic Reference

Bibliography references can be cited from within any description element in the Data Model; for example, from within object descriptions, parameter descriptions, enumeration descriptions, etc. This is done by using a {{bibref}} Template (see I.2.3).

In order to cite a bibliographic reference, the reference definition must be “visible” from within the local file making the citation. This is accomplished by either importing the file that defines the reference or by defining the reference directly within the local Data Model file.

In the following Data Model listing, the global bibliography file tr-069-biblio.xml is imported in order to gain access to its defined reference elements. Then the EnabledOptions parameter description cites TR-069 Table 48 using the notation {{bibref|TR-069|Table 48}}. The second part of the Template is the id of the bibliographic reference being cited, and the (optional) third part of the Template is free-form text indicating a specific area of the document being cited.

In this case it is Table 48, however, this value will vary depending on the area of the document being cited (e.g. Section, Appendix, Annex, Table, Figure, etc.).

<dm:document xmlns:dm="urn:broadband-forum-org:cwmp:datamodel-1-0" ... spec="urn:broadband-forum-org:tr-069-1-0-0">

...

<import file="tr-069-biblio.xml" spec="urn:broadband-forum-org:tr-069-biblio"/> ...

<model...> <object ...>

<parameter name="EnabledOptions" access="readOnly">

<description>... as described in {{bibref|TR-069|Table 48}}.</description> </parameter> ... </object> ... </model> </dm:document>

In the following Data Model listing, bibliography reference RFC 4078 is defined directly within the local file. Then the ContentReferenceId parameter description cites RFC 4078 using the notation {{bibref|RFC4078}}. The RFC4078 portion is the id of the bibliographic reference being cited. In this case the reference is visible (available to be used within bibref Templates) because it is defined directly within the local file.

<dm:document xmlns:dm="urn:broadband-forum-org:cwmp:datamodel-1-3" ... spec="urn:broadband-forum-org:tr-135-1-1-0"> ... <bibliography> <reference id="RFC4078"> <name>RFC 4078</name>

<parameter name="ContentReferenceId" access="readOnly">

<description>Unique Content Item reference as defined in {{bibref|RFC4078}}</description> ... </parameter> </object> ... </model> </dm:document>

In document TR-154 TR-069 Data Model XML User Guide (Page 54-58)