Subsections


3. XBEL Document Structure

This section describes the structure of XBEL documents. This includes information on each element and attribute defined in the DTD. Some descriptions include references to the parameter entities used to construct the DTD; these are described in Section 4.1, ``Use of Parameter Entities.''


3.1 Date/time Attribute Values

Several attributes defined in this document type require date/time values stored as CDATA. For these attributes, the value must be formatted as an ISO 8601:1988 value containing a date [fS88,Hou93,Kuh98]. A time value should be supplied whenever the information is available to the application which set the value. The format of the values is restricted to the forms specified in the profile defined in Date and Time Formats [WW98]. Attributes which require this form of value are described below as having a date/time value rather than a CDATA value.


3.2 Top-level Information

This section describes the top-level element type of XBEL documents.


3.2.1 The <xbel> Element

The <xbel> element defines the top-level data structure stored in an XBEL instance. It may contain optional <title>, <info>, and <desc> elements, followed by any number of elements from %nodes.mix;. This is similar to the <folder> element, but it may not be nested and carries different attributes.

Attributes

The <xbel> element carries a version attribute which has a fixed value that specifies the version of the XBEL DTD. Other attributes indicate the similarity to the <folder> element.

version, fixed
Fixed value which specifies the version of the DTD in use.

id
ID value to allow linking to this element; only the <alias> element's ref attribute supports a corresponding IDREF value.

added
Date/time value which can be used to record when the collection of bookmarks was created.

Processing Expectations

The <xbel> element is in many ways similar to a <folder> element, but may not be ``folded.'' Auxillary information, such as an optional <title> element, may be shown in a substantially different way than for <folder> in a user interface.


3.3 Common Elements

Elements described in this section may occur in different contexts within an XBEL instance, but share fundamental semantic interpretation in each case.


3.3.1 The <title> Element

The <title> element is used to mark the title associated with the immediately enclosing element. It is used for the <xbel>, <folder>, and <bookmark> elements. This element is always optional and may contain only character data.

Processing Expectations

Software which presents bookmark information to the user in any form should use the content of this element to identify the resource to the user. Additional information may be needed to make the identification unambiguous.

Applications may use the text of the <title> during search operations.

Rationale

Many Internet resources are described by a short title, often displayed by the bookmarking facilities. Storing the title allows a significant improvement in user interface responsiveness when compared to retrieving the resource to reload the title. Title storage is the approach taken by all browsers known to the XBEL designers.


3.3.2 The <desc> Element

The <desc> element is used to store a human-readable description of the enclosing element. For a <folder> or the <xbel> element, this may be used to more thoroughly explain the subject of the bookmarks stored in the collection and why they may be interesting. For a <bookmark>, a summary of the resource pointed to by the bookmark may be more appropriate. This element is always optional and may contain only character data.

Processing Expectations

The content of this element may be displayed to a user requesting more information on the folder or bookmark containing the description. In the case of a <bookmark>, this can be used before actually making a request over the network to retrieve the resource.

Applications may use the text of the <desc> during search operations.

Rationale

Many Internet browsers support simple annotation of bookmark data with human readable text. This element is required to support exchange of this data.


3.3.3 The <info> Element

The <info> element is used to store metadata related to the immediately enclosing element. The intended use is for <info> to store a series of <metadata> elements, each of which ``belongs'' to some application. An ``application'' in this sense may be either a program, such as a specific Internet browser, or a more general metadata scheme, such as the Dublin Core [Dub97].

The <info> element is always optional. If present, it must contain one or more <metadata> elements.

Processing Expectations

Applications are expected to ignore <info> elements if they are not able to deal with the contents of constituent <metadata> elements. Whether or not <info> elements should be ``passed through'' transparently or removed depends on the purpose of the processing application, but an effort should be made to retain the information whenever the enclosing element is retained, even in a modified form.

Rationale

This element provides a clean way of isolating application-specific metadata from more generally supported constructs within the bookmark data.


3.3.4 The <metadata> Element

The <metadata> element is used as a container for all auxillary information related to a node which belongs to a single metadata scheme. The specific contents of <metadata> is highly dependent on the metadata scheme which applies; XML namespaces should be used to identify explicit markup used within the element.

<metadata> elements are always optional. Note that an <info> element which contains no <metadata> elements must be removed.

Attributes

owner, required
CDATA value specifies the application which ``owns'' the content of the element. The value of this attribute should be a URI which refers to a definition of the application and content structure in either human- or machine-processible form. It is not required that the URI be addressable through the network.

It is expected that namespace attributes will be added to the element to specify the markup defined for the content of the <metadata> element.

Processing Expectations

Within an <info> element, each <metadata> element is required to have a unique value for the owner attribute. Programs which modify the contents of <metadata> elements should ensure that only one <metadata> exists for any owner value normally modified by the application within affected <info> elements. <metadata> elements for other owners should remain unaffected.

Specific interpretation of <metadata> content is highly dependent on both the owner and the application, and is not otherwise within the scope of this document.

Rationale

The <metadata> element is required to support owner identification. It is entirely reasonable for multiple owners of data to share a document type for their information, but otherwise require separate processing. The Resource Description Framework provides an example of an approach which would require multiple applications to share a namespace [LS98,BGL98]. Some additional form of ownership identification is required to ensure processors can avoid destroying each other's data.


3.4 Data Organization

The elements described in this section are used to impose organization on a collection of <bookmark> nodes. <folder> is used to support hierarchical organization and <separator> is used to support non-hierarchical organization.


3.4.1 The <folder> Element

The <folder> element is the element used to support hierarchical data organization. It is the only element type which is allowed to nest within itself.

This element may contain optional <title>, <info> and <desc> elements. After this, any number of elements from %nodes.mix; are allowed.

Attributes

id
ID value to allow linking to this element; only the <alias> element's ref attribute supports a corresponding IDREF value.

added
Date/time value which records when the folder was added to the bookmark collection represented by the instance.

folded
Token which records whether the contents of the folder should be displayed by default in a user interface. The value may be yes or no.

Processing Expectations

User interfaces should display <folder> elements as collapsing lists, allowing the user to display or hide the contents of the element on demand. Appropriate behavior outside of user interfaces is expected to be application specific.

Rationale

The <folder> element may be used to represent hierarchical relationships within a collection of bookmarks, as deployed in current Internet browsers.


3.4.2 The <separator> Element

The <separator> element can be used to separate bookmarks within a collection in a non-hierarchical fashion. It may be used within a <folder> or the <xbel> element.

Processing Expectations

The presence of this element may be represented by displaying a horizontal line or vertical whitespace in an interactive user interface or printed representation.

Rationale

A simple separator is required to support the bookmark structures of existing Internet browsers.


3.5 Bookmark Data

Only one element type is used to encapsulate information specific to an individual bookmark. No need for alternate elements has been demonstrated.


3.5.1 The <bookmark> Element

A <bookmark> element is used to store information about a specific resource. This element may contain the optional elements <title>, <info> and <desc>.

Attributes

The <bookmark> element carries more attributes than other elements defined in XBEL. These attributes are used to carry much of the common information maintained on bookmarks by the major browsers.

href, required
URI which specifies the resource described by the <bookmark> element.

id
ID value to allow linking to this element; only the <alias> element's ref attribute supports a corresponding IDREF value.

added
Date/time value which indicates when the <bookmark> element was added to the bookmark collection.

modified
Date/time value which records the time of the last known change to the resource identified by the <bookmark>.

visited
Date/time value which represents the time of the user's last ``visit'' to the resource. Note that the value for modified may be more recent than the value for visited if software is used that checks for resources which have changed since the user last visited the resource. This feature is increasingly common in browsers.

Processing Expectations

In a user interface, <bookmark> should typically be represented by the contents of the <title> element, if present. The representation of the bookmark should be ``hot,'' allowing traversal to the referenced resource by the user. Additional information on the resource, such as the description given in a <desc> element, should be available to the user on demand.

Outside a user interface, processing may be too application-specific to discuss here.

Rationale

The use of a single structured element type to represent external resources simplifies processing while allowing a rich set of information to be maintained on each resource.


3.6 Internal References

A single element is provided to support internal references to other elements within an XBEL instance.


3.6.1 The <alias> Element

Attributes

Only one attribute is needed for <alias>, and is required to identify the link referent.

ref, required
IDREF value which refers to a <bookmark> or <folder> element, or the document <xbel> element.

Processing Expectations

Software which presents bookmarks in a user interface should distinguish aliases from other bookmarks visually, but otherwise allow examination of the referent transparently. Netscape Navigator does this by presenting the bookmark title in an italic font; the appropriate visual distrinction is likely to be dependent on other aspects of the user interface.

Outside of user interface considerations, treatment of aliases is application-specific. However, some guidance may prove useful. When encountering an <alias>, an application should only need to traverse the <alias> and process the referent if that referent would not otherwise be processed, otherwise, the <alias> may usually be ignored. This should become an issue only when the application is processing a portion of the bookmark hierarchy rather than the complete tree.

Rationale

Netscape Navigator and Microsoft Internet Explorer bookmarks can include ``aliases'' to other nodes in the hierarchical structure. Navigator supports only aliases to bookmark nodes, while Internet Explorer also supports aliases to folders.

Navigator's format simply adds the attribute aliasid to nodes which are referred to be aliases, and the attribute aliasof to the actual alias. All other information is duplicated for each alias of the primary bookmark entry. XBEL uses a distinct element and the ID/IDREF mechanism provided by XML to avoid redundency and support validation.