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.
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.
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.
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.
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.
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.
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.
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.
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.
- 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.
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.
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.
- 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.
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.
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.
The presence of this element may be represented by displaying
a horizontal line or vertical whitespace in an interactive
user interface or printed representation.
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>.
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.
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.
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
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.
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.
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.