Using the Document Properties and SmartTags Elements in Office Documents

A number of elements in the "urn:schemas-microsoft-com:office:office" namespace (referred to in this document as the Common Properties namespace) are used in several applications in the Microsoft Office 2003 Editions. This document reviews the following elements:

There is no root element to contain the elements in the Common Properties namespace. Instead, the elements in the Common Properties namespace are used by other XML dialects within the root element defined for that document type. For example, in a WordprocessingML document, the DocumentProperties element of the Common Properties namespace appears as the first child element within the WordprocessingML wordDocument root element:

<w:wordDocument xmlns:w="http://schemas.microsoft.com/office/word/2003/wordml" xmlns:o=

"urn:schemas-microsoft-com:office:office" xml:space="preserve">

<o:DocumentProperties> <o:Title>A Document</o:Title>

<o:Revision>22</o:Revision> </o:DocumentProperties>

<w:fonts> ...remainder of WordProccessingML document...

Document Properties and Custom Properties

The information contained in these properties elements is displayed on the Document Properties dialog box associated with a document, on the Summary, Statistics, and Custom tabs.

The information on the Summary and Statistics tabs is contained in the DocumentProperties element. Custom properties are contained in the CustomDocumentProperties element.

The DocumentProperties Element

For many of the child elements of the DocumentProperties element, an application may both generate information for document properties as part of creating an Office document and read those elements to obtain information about document properties. For a number of these elements, however, it's unlikely that an application generates the information explicitly (for example, statistics related to the document such as the number of characters or number of pages). Should an application write this information to an Office document, the Office application may ignore the information. For example, Microsoft Office Word 2003 uses the values it finds in the Words and Pages elements only for the length of time that it takes to generate actual counts— typically the time that it takes to load the document. The primary purpose for these elements is to provide other applications with information about a document after it is processed in Word. The elements within the DocumentProperties element are not required to appear in any particular order. Not all Office applications write out all of these elements to the XML document. For example, for the automatically generated statistics, Microsoft Office Excel 2003 saves only the Created and Version elements.

Table 1. Elements of the DocumentProperties element

ElementData TypeDescription
TitlestringThe title of a document. The title can be different from the file name and is used when searching for the file and when creating Web pages from the file.
SubjectstringThe subject of the document. This property can be used to group similar files, so you can search for all files that have the same subject.
KeywordsstringKeywords to be used when searching for the document.
DescriptionstringComments to be used when searching for the document.
CategorystringThe category of the file. This property can be used to group similar files, so you can search for all the files that have the same category.
AuthorstringThe name of the person who first created the document. The name of the person who last saved the document is contained in the LastAuthor element.
LastAuthorstringThe name of the person who last saved the document. The original author is contained in the Author element.
ManagerstringThe name of the author's manager. This property can be used in searches to group all the documents of authors having the same manager.
CompanystringThe author's employer. This property can be used in searches to group all of the documents from the same company.
HyperlinkBasestringThe path or URL that is used for all hyperlinks with the same base address in a document. This property can be an Internet address (for example, http://www.microsoft.com), a path to a folder on your hard disk (for example, c:\personal\documents), or a path to a folder on a network (for example, \\exampleserver\public\documents).
RevisionintegerThe number of times the document was saved. If no change was made since the document was last saved, this number is not updated in Word.
PresentationFormatstringThe viewing format of a document.
GuidstringA unique identification number for the document.
AppNamestringThe name of the application that last updated the document. Word and Excel do not update this element.
Versionversion*The version of the application used to create the document. Word and Excel update this element.
TotalTimeintegerThe number of minutes since it was created that the document was open for making changes (even if no changes are made).
LastPrinteddate/time**The date and time that the document was last printed. Word omits this element if the document has not been printed.
Createddate/time**The date and time that the document was created.
LastSaveddate/time**The date and time that the document was last saved.
PagesintegerAn estimate of the number of pages in the document.
WordsintegerAn estimate of the number of words in the document.
CharactersintegerAn estimate of the number of characters in the document, not counting spaces.
CarachersWithSpacesintegerAn estimate of the number of characters in the document, counting spaces.
BytesintegerAn estimate of the number of bytes in the document.
LinesintegerAn estimate of the number of lines in the document.
ParagraphsintegerAn estimate of the number of paragraphs in the document.
* The format for the Version value is n.nn.
** The format for date/time fields is yyyy-mm-ddThh:mm:ssZ. (This format can be described as follows: a four-digit year, hyphen, two-digit month, hyphen, two-digit day, uppercase letter T, two-digit hour, colon, two-digit minute value, colon, two-digit seconds value, uppercase letter Z. Only seconds may be fractional).

The following is an example of a DocumentProperties section in an XML document:

<o:DocumentProperties>

    <o:Title>Office XML Primer</o:Title>

    <o:Subject>Selected tags from the Common Properties namespace</o:Subject>

    <o:Author>Holly Dickson</o:Author>

    <o:Keywords>Microsoft Office office namespace xml</o:Keywords>

    <o:Description>This document includes information about the DocumentProperties, SmartTags,

    and CustomProperties elements and their children.</o:Description>

    <o:LastAuthor>Holly Dickson</o:LastAuthor>

    <o:Revision>9</o:Revision>

    <o:TotalTime>9</o:TotalTime>

    <o:Created>2003-10-21T16:23:00Z</o:Created>

    <o:LastSaved>2003-10-21T16:33:00Z</o:LastSaved>

    <o:Pages>2</o:Pages>

     <o:Words>1016</o:Words>

    <o:Characters>5125</o:Characters>

    <o:Category>Office XML</o:Category>

     <o:Manager>Toby Nixon</o:Manager>

    <o:Company>Northwind Traders</o:Company>

    <o:HyperlinkBase> http://www.northwindtraders.com/ </o:HyperlinkBase>

    <o:Lines>160</o:Lines>

    <o:Paragraphs>6</o:Paragraphs>

    <o:CharactersWithSpaces>7125</o:CharactersWithSpaces>

    <o:Version>11.5329</o:Version>

</o:DocumentProperties>

The CustomDocumentProperties Element

In addition to the predefined document property elements, you can save information in an XML document in Office by using custom properties. Custom properties allow the application to define new name/value pairs and save them in the document. Custom properties are held in the CustomDocumentProperties element. Within the CustomDocumentProperties element, the name of the custom property is the name of the element that holds the value for the custom property. This new element is associated with the Common Properties namespace. The new element has an attribute called dt that specifies the value's data type. (The dt attribute is associated with the "uuid:C2F41010-65B3-11d1-A29F-00AA00C14882" namespace.) The dt attribute can have one of four values:

In the following example, the following data is saved:

<o:CustomDocumentProperties xmlns:o="urn:schemas-microsoft-com:office:office" xmlns:dt=

"uuid:C2F41010-65B3-11d1-A29F-00AA00C14882" >

    <o:Editor dt:dt="string">Frank Miller</o:Editor>

    <o:LastReview dt:dt="dateTime.tz">1997-02-28T23:00:00Z</o:LastReview>

    <o:EditPasses dt:dt="float">3</o:EditPasses>

    <o:StyleGuideCompliant dt:dt="boolean">1</o:StyleGuideCompliant>

</o:CustomDocumentProperties>

Smart Tags

Two elements contain information related to smart tags: SmartTagType and SmartTags.

The SmartTagType element declares what smart tags appear in the document. In a document that contains different types of smart tags, there are multiple SmartTagType elements. However, in a document where the same type of smart tag appears multiple times, only a single SmartTagType element is required. The SmartTagType element appears in different places in different documents. In Excel, for example, it is the first child of the root element (the Workbook element).

A SmartTagType includes two pieces of information: the namespace for the SmartTags element and the name of the root element of the smart tag. The namespace appears in the namespaceuri attribute of the SmartTagType element and the root element name appears in the name attribute of the SmartTagType element. In addition, the SmartTagType element can have a url attribute, which points to a URL required by the smart tag.

In the following example, the MapPoint geoheading smart tag is declared for use in the document:

<SmartTagType namespaceuri="urn:schemas-microsoft-com:mappoint:smarttags" name=

"geoheading" xmlns="urn:schemas-microsoft-com:office:office"/>

Within the document, the SmartTags element marks where smart tags appear in the document. In different document types, the SmartTags element appears in different places. When used in Excel, for example, the SmartTags element appears as the first child of the Cell element.

The SmartTags element doesn't define any particular smart tag. The SmartTags element is rather a container for the elements that specify the smart tag used in a document. The SmartTags element has no attributes and can contain any well-formed XML content.

In the following example, the SmartTags element contains the geoheading smart tag declared in the previous example:

<SmartTags xmlns="urn:schemas-microsoft-com:office:office" xmlns:st1="urn:schemas-microsoft-com:mappoint:smarttags">

    <st1:geoheading GeoFieldType="3:NA,3:EUR" GeoCountry="0:NA,0:EUR"/>

</SmartTags>

The elements corresponding to smart tags that appear inside the SmartTags element belong to the namespace from the namespaceuri attribute of the SmartTagType element in which the smart tag was declared. That namespace must be defined somewhere in the document, and it must be associated with the elements that define the smart tag. In the previous example, the prefix "st1" was defined and associated with the namespace as part of the SmartTags element.

©2003-2004 Microsoft Corporation. All rights reserved. Permission to copy, display and distribute this document is available at: http://msdn.microsoft.com/library/en-us/odcXMLRef/html/odcXMLRefLegalNotice.asp