Developer Info: Collection XML Schema

Collection XML (CXML) is the schema used to describe structured data to be displayed in the PivotViewer collection experience. This page contains detailed information about this schema in the following sections:

Hello World Example
Schema Structure
Element Overview
Schema Details

At a high-level, CXML can be thought of as a set of property/value pairings. Facets are like property values on an item, and facet categories are groups of facets. For example: if a collection had a facet category called "U.S. State," then "Georgia" could be a facet in that category. Depending on authoring choices, these facets may be displayed as filters in the PivotViewer collection experience, or included in the details of an item.

Hello World Example

The following sample XML specifies a simple collection with only one item.


<?xmlversion="1.0"?>
<CollectionName="Hello World Collection"SchemaVersion="1.0"
xmlns="http://schemas.microsoft.com/collection/metadata/2009"
xmlns:p="http://schemas.microsoft.com/livelabs/pivot/collection/2009" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <FacetCategories>
    <FacetCategory Name="Hello World Facet Category One" Type="String"/>
  </FacetCategories>
  <Items ImgBase="helloworld.dzc">
    <Item Img="#0" Id="0" Href="http://www.getpivot.com"Name="Hello World!">
      <Description>This is the only item in the collection.</Description>
      <Facets>
        <Facet Name="Hello World Facet Category One">
         <String Value="Hello World Facet Value"/>
        </Facet>       
      </Facets>
    </Item>
  </Items>
</Collection>

Now, let’s look at how each part of the XML is surfaced in the PivotViewer.

As you can see, a basic collection can be created with a small amount of XML. Much of the work, and much of the schema, revolves around fine-tuning the presentation of the data. Please read below for further details, and also see Designing Collections and Collection Tools for tips.

Schema Structure

A collection for the PivotViewer consists of CXML and a corresponding image asset collection. The CXML begins with a top-level container called Collection. The Collection node contains top-level properties and elements which pertain to the entire set of items contained within the collection.

The FacetCategories section is a child of the Collection node. For each facet attached to an item, a corresponding facet category must exist. Here, the name of the facet, the type, a format string, and various visibility options can be set. The Type field can be Number, String, LongString, DateTime, or Link.

Another child of Collection is the Items node. Because this is where each individual item in the collection is defined, this node usually contains the majority of the information in the file. Each item can have properties such as a double-click action link, Href; a name, Name; a description, Description; an id, Id; an image asset, Img; or any number of custom properties declared in the Facets section.

PivotViewer Reference

For reference, use the following table to identify the various parts of the Silverlight PivotViewer.

Element Overview

The following table contains a summary of the key elements in CXML, and their attributes.

Element Name	Type	Description	Key Attributes
Collection	xs:Element	Top-level container for everything in the collection.	Name – Name of the collection which appears in the PivotViewer title bar. Icon – Icon representing the collection which appears with thumbnails of the collection (in history, for example). BrandImage – Image that appears left-most in the PivotViewer title bar. Typically used for branding. AdditionalSearchText – Specifies an additional string to append to search queries used for Bing search results in the info panel. E.g. if the item title is "Justin Miller" and the string specified is "baseball player", the Bing query will be "Justin Miller baseball player." To disable Bing queries entirely, set the value to "__block". SchemaVersion – Should match the schema version in the xsd. Optional. xml:lang – An XML language code (e.g. “de” or “fr-CA”). This attribute sets which language PivotViewer uses to alphabetically sort string facet values, and to display data defined in the CXML. Optional.
FacetCategory (child of Collection)	xs:ComplexType	A grouping of facets. Note that all values (see children of Facet below) for a FacetCategory must be of the same type.	Name – Name of the category which appears in the PivotViewer filter panel and in the info panel. Format – Optional .NET format string to be used for numeric types. It is recommended that data be rounded/truncated to match the format string to avoid potentially undesired behavior when filtering on that facet in the PivotViewer Graph View. Type – One of String, LongString, Number, DateTime, or Link. Note that all values for a FacetCategory must be of the same type. IsFilterVisible – Determines whether the category appears in the filter panel. Can only be true for categories of type String, Number, or DateTime. IsMetaDataVisible – Determines whether the category is visible in the info panel. IsWordWheelVisible – Determines whether the category is included in keyword filters over that collection. This attribute can only be true for categories of type String, LongString, or Link.
Items (child of Collection)	ItemList	Container for all the items in the collection.	ImgBase – Specifies a relative path to the Deep Zoom DZC containing this collection’s images.
Item (child of Items)	xs:ComplexType	An individual item in a collection.	Img – Uri of the image. With Deep Zoom DZCs, uses the URI fragment identifier, "#", as an index into an image collection. E.g. the image with item id x in the DZC specified by the ImgBase attribute of Items would be accessed with the string "#x." Id – Unique id of this item in the ItemList. Href – A URL associated with this item. Double-clicking the item in PivotViewer will navigate the user to this URL. Name – The name of the item which will appear in the info panel.
Description (child of Item)	xs:String	A text description of an item to be displayed in the info panel.	Value - A non-empty string.
Facet (child of Item)	xs:ComplexType	A container for a value (String, LongString, Number, DateTime, or Link) of a property (FacetCategory) on an item. May be used to filter, sort, or display detailed information about an item.	Name – A non-empty string. The name must match the name of the FacetCategory for which it contains values.
String (child of Facet)	StringType	A string facet value.	Value – A non-empty string.
LongString (child of Facet)	StringType	A string facet value that appears in the info panel only. Used for text longer than a short sentence, for optimized multi-line display.	Value – A non-empty string.
Number (child of Facet)	NumberType	A number facet value.	Value – An xs:decimal.
DateTime (child of Facet)	DateTimeType	A DateTime facet value.	Value – An xs:dateTime.
Link (child of Facet)	LinkType	A hyperlink that appears in the info panel only. Used to link to related collection or web-pages.	Href – An URL. Name – A non-empty string.

Schema Details

The PivotViewer CXML schema itself is available via the following XSD document: PivotCollection.xsd.

When creating CXML, the following namespaces should be used:

xmlns="http://schemas.microsoft.com/collection/metadata/2009"
xmlns:p="http://schemas.microsoft.com/livelabs/pivot/collection/2009"

Fine-Tuning With PivotViewer Schema Extensions

To provide fine-tuned presentation of a collection’s display, the PivotViewer team has added some types in the form of extensions to our simpler schema (Collection.xsd).

Key extension elements are listed in the table below.

Element Name	Type	Element Fine-Tuned	Description	Key Attributes
Related	RelatedList	Item	Contains a sequence of RelatedLinkTypes related to an item. Typically used to cross-link multiple collections to create a Linked Collection.
Link	RelatedLinkType	Item	A link to a web-page or collection related to the item. Used in a sequence in a RelatedList.	Href – An URL. Name – A non-empty string.
Copyright	RelatedLinkType	Collection	Used to specify a link to copyright information relating to the content in the collection. The link appears in the bottom of the info panel.	Href – An URL. Name – A non-empty string.
DateRange	xs:Element	DateTime	Allows DateTime elements to optionally provide upper and lower bounds.	Name – A non-empty string. LowerBound – An xs:dateTime. UpperBound - An xs:dateTime.
SortOrder	SortOrderList	String	Used to specify a sort order for string facets in the PivotViewer filter panel and column order in the Graph View. Is parented by a FacetCategory, contains SortValues.	Name – A non-empty string.
SortValue	SortValueType	String	Used to specify sort order, using the document order of items in the parenting SortOrderList.	Value – A non-empty string representing a possible value for the facet.

The two files used to enable these extensions are:

PivotCollectionExtensions.xsd – Describes new element and attribute definitions that extend the simpler collection schema to support PivotViewer needs, such as supplying branding icons.
PivotCollection.xsd – A modified copy of the simpler schema which describes the application of the extensions to the simpler schema.

Schema Extensions

The collection schema that PivotViewer typically uses is actually an extension of a simpler schema (Collection.xsd) for ascribing metadata to images. This section provides more context to understand how PivotViewer schema extensions work.

To extend the simpler CXML schema, two files are required: a modified copy of the simpler schema and a second file which will contain new element and attribute definitions. These new elements and attributes are placed in the modified simpler schema under a different namespace. For example, to add the attribute Icon to the element Collection, the following changes to the definitions schema (ex: PivotCollectionExtensions.xsd) and modified version of the simpler schema (ex: PivotCollection.xsd), respectively, are required:

<xs:attributename="Icon"type="xs:anyUri"/>                      
<xs:Elementname="Collection">
  <xs:complexType>
        <xs:attribute name="p:Icon">
  </xs:complexType>
</xs:element>

In the above example, p is defined by an XML namespace (xmlns) declaration which points to the namespace which contains definitions for the new attributes and elements.

Similarly, to add a new element called Related to Item, the following changes are required.

                  
<xs:complexType>name="itemExtension">
  <xs:sequence>
        <xs:element name="Related"type="relatedList"minOccurs="0"maxOccurs="1">
  </xs:sequence>
</xs:complexType>                  
<xs:complexType>
name="item">
  <xs:sequence>
        <xs:element name="Extension"type="p:itemExtension"minOccurs="0"maxOccurs="1">
  </xs:sequence>
</xs:complexType>

Compression

Given the large amount of text typical in CXML files, it is recommended that files be compressed before being sent over the wire. As such, the mime type should be set to "text/xml." Note that most web servers will compress this mime type by default (including IIS and Apache).

Versioning

Given the nature of this release, the CXML schema is likely to change in the future. With each extension to the schema, the Version attribute will be incremented by an amount less than one to signal a non-breaking change. While it is the intention of the PivotViewer team to make future schema changes in a backward-compatible manner, this may not always be possible. In the event of a breaking change, the Version attribute will be incremented to the next whole number. Note also that the SchemaVersion attribute on the Collection element in a CXML document should be used to track the schema version used for a given collection.