Using Content Types to Specify XML Document Properties

This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

When Windows SharePoint Services invokes the built-in XML parser to parse XML files, the parser uses the document's content type to determine which document properties map to which content type columns, and where those document properties are stored in the document. Therefore, to have Windows SharePoint Services use the built-in XML parser with your XML files, you must do the following:

• Create a content type that includes the necessary parsing information. For each document property you want to promote or demote, include a field definition that includes the name of the document property that maps to the column the field definition represents, and where the document property is stored in the document.

• Make sure that the content type ID is a document property that is demoted into the document. This ensures that the built-in XML parser can identify and access the correct content type for the document. For more information, see Specifying Document Content Type for XML Parsing.

Content Type Information for XML Parsing

Document properties are promoted to and demoted from columns on the document library in which the document is stored. If the document is assigned a content type, these columns are specified in the content type definition. In the content type definition XML, each column included in the content type is represented by a FieldRef element.

Because of this, to specify the information the built-in XML parser needs to promote and demote a document property, you must edit the FieldRef element that represents the document property's corresponding column in the content type definition.

The following figure shows the actions the parser takes when an XML file is checked in to a document library. Windows SharePoint Services invokes the parser, which looks at the content type ID column to determine the location in the document where its content type ID is stored. The parser then looks inside the document for its content type at this location. The parser examines the content type to determine which FieldRef elements contain document property information. For each FieldRef element mapped to a document property, the parser looks for the document property at the location in the document specified in the matching FieldRef element. If the parser finds the document property at the specified location, it promotes that value to the matching column.

When an XML document is first uploaded to a document library, the built-in XML parser must determine the content type of the document, and whether that content type is associated with the document library. For more information, see Specifying Document Content Type for XML Parsing.

You can edit several attributes in a Field or FieldRef element to map that element to a document property and specify the location of the property in the document.

First, the Field or FieldRef element must contain an ID attribute that specifies the ID of the column in the document library. For example:

<FieldRef

ID="{4B1BF6C6-4F39-45ac-ACD5-16FE7A214E5E}"

Name="EmployeeID”/>

Next, add additional attributes to the Field or FieldRef element that specify the location of the document property in the document. Document properties can be stored in the following locations:

• The XML content of the document

• The processing instructions of the document

The attributes you add to the Field or FieldRef element to specify the property location depends on whether the property is stored as XML content or processing instructions. These attributes are mutually exclusive; if you add an attribute that specifies a location in the XML content, you cannot also add attributes that specify a location in the processing instructions.

To edit a column's field definition schema programmatically, use the SPField.SchemaXML object.

Specifying Properties in Document XML Content

If you store the document property in the document as XML content, you specify an XPath expression that represents the location of the property within the document. Add a Node attribute to the Field or FieldRef element, and set it equal to the XPath expression. For example:

<FieldRef

ID="{4B1BF6C6-4F39-45ac-ACD5-16FE7A214E5E}"

Name="EmployeeID"

node="/my:myFields/my:employee"/>

Document Property Value Collections

If you specify an XPath expression that returns a collection of values, you can also include an aggregation attribute in the Field or FieldRef element. The aggregation attribute specifies the action to take on the value set that is returned. This action can be either an aggregation function or an indication of the particular element within the collection.

Possible values include the following:

• sum

• count

• average

• min

• max

• merge

• plaintext   Converts node text content into plain text.

• first   Applies property promotion and demotion to the first element in the collection.

• last   Applies property promotion and demotion to the last element in the collection.

For example:

<FieldRef

ID="{4B1BF6C6-4F39-45ac-ACD5-16FE7A214E5E}"

Name="TotalToExpense”

node="/my:myFields/my:expense"

aggregation="sum"/>

Specifying Properties in Document Processing Instructions

Because processing instructions can contain data other than just XML, XPath expressions are insufficient to identify document properties stored in processing instructions. Instead, you must add a pair of attributes to the Field or FieldRef element that specify the processing instruction and processing instruction attribute you want to use as a document property:

• Add a PITarget attribute to specify the processing instruction in which the document property is stored in the document.

• Add a PIAttribute attribute to specify the attribute to use as the document property.

For example:

<FieldRef

ID="{4B1BF6C6-4F39-45ac-ACD5-16FE7A214E5E}"

Name="columnName"

PITarget="mydocumenttype"

PIAttribute="propertyAttribute"/>

These attributes instruct the parser to examine the following processing instruction and attribute for the document property value:

<?mydocumenttype propertyAttribute="value"?>

You can also add another pair of attributes, PrimaryPITarget and PrimaryPIAttribute. This attribute pair is optional. Like PITarget and PIAttribute, they work in unison to identify the location of the document property. However, if they are present, the built-in XML parser looks for the document property in the location they specify first. If there is a value at that location, the parser uses it and ignores the PITarget and PIAttribute attributes. The parser looks for the document property at the location specified by the PITarget and PIAttribute attribute pair only if the location specified by the PrimaryPITarget and PrimaryPIAttribute attributes returns a null value.

If you specify the PrimaryPITarget and PrimaryPIAttribute attributes, you must also specify PITarget and PIAttribute attributes. The parser uses the PrimaryPITarget and PrimaryPIAttribute attributes only if the processing instruction attribute specified by the PITarget and PIAttribute pair does not exist in the document, not if that attribute exists but is null or empty.

See Also

Concepts

XML Document Property Promotion and Demotion

XML Parser Processing

Determining Document Content Type for XML Parsing

Specifying Document Content Type for XML Parsing