Categories Definition Schema Reference

You use the CATEGORIES element to define one or more categories for grouping work item types.

Schema Hierarchy

CATEGORIES Element (CATEGORIES Definition Schema)

**    CATEGORY Element (CATEGORIES Definition Schema)**

**        DEFAULTWORKITEMTYPE Element (CATEGORIES Definition Schema)**

**        WORKITEMTYPE Element (CATEGORIES Definition Schema)**

<xs:element name="CATEGORIES">
<xs:element name="CATEGORY" minOccurs="0" maxOccurs="unbounded">
<xs:element name="DEFAULTWORKITEMTYPE" type="WorkItemTypeRef" />
<xs:element name="WORKITEMTYPE" type="WorkItemTypeRef" minOccurs="0" maxOccurs="unbounded"/>

<CATEGORIES>
   <CATEGORY name="category display name" refname="category reference name">
      <DEFAULTWORKITEMTYPE name="work item type reference name" />
      <WORKITEMTYPE name="work item type reference name" />
   </CATEGORY>
</CATEGORIES>

Attributes and Elements

The following sections describe the attributes and elements for the categories XML file.

Child Elements and Attributes

Element	Attribute	Description
CATEGORIES		Required element within the XML categories file. Container element for specifying one or more CATEGORY elements that are defined for a team project.
CATEGORY		Required CATEGORIES child element. Specifies a named category group that contains one default DEFAULTWORKITEMTYPE element and zero or more WORKITEMTYPE elements.
	name	Required CATEGORY attribute. The attribute type is typelib:FriendlyName. Specifies the display name of the category. Must be between 1 to 254 characters and unique within the team project.
	refname	Required CATEGORY attribute. The attribute type is typelib:ReferenceName. For more information, see Naming Conventions for Work Item Tracking Objects.
DEFAULTWORKITEMTYPE		Required CATEGORY element. Specifies a work item type to be tagged as belonging to the named category and to be used as the default type for the category.
	name	Required DEFAULTWORKITEMTYPE attribute. The attribute type is WorkItemTypeRef. Specifies the reference name of a valid work item type for the team project that will be used as the default type for the category.
WORKITEMTYPE		Optional CATEGORY element. Specifies a work item type to be tagged as belonging to the named category.
	name	Required WORKITEMTYPE attribute. The attribute type is WorkItemTypeRef. Specifies the reference name of a valid work item type for the team project that will belong to the named category.

Remarks

CATEGORIES is the root element of the categories schema.

A category is defined within the CATEGORIES set of CATEGORY elements that is stored and used by a team project. Each CATEGORIES element must have at least one CATEGORY element defined.

A category cannot be empty. Each CATEGORY element must have at least one DEFAULTWORKITEMTYPE or WORKITEMTYPE element defined.

Each category has a friendly name and a reference name that must be unique within the team project. Each category friendly name must meet the following requirements:

• Names can have up to 254 Unicode characters.

• Names must not be empty.

• Names cannot have leading or trailing white spaces.

• Names cannot contain backslash (\) characters.

• Names cannot contain two consecutive white spaces.

Category friendly names are not localized and cannot be made into a token, whereas the names for work item types are localized and can be made into a token.

For reference naming conventions, see Naming Conventions for Work Item Tracking Objects.

Example

The following example specifies a categories XML file that can be imported to a team project. It defines four categories and assigns only a default work item type for each.

<?xml version="1.0" encoding="utf-8"?>
<cat:CATEGORIES xmlns:cat="https://schemas.microsoft.com/VisualStudio/2008/workitemtracking/categories">
   <CATEGORY refname="Microsoft.BugCategory" name="Bug Category">
      <DEFAULTWORKITEMTYPE name="Bug" />
   </CATEGORY>
   <CATEGORY refname="Microsoft.RequirementCategory" name="Requirement Category">
      <DEFAULTWORKITEMTYPE name="User Story" />
   </CATEGORY>
   <CATEGORY refname="Microsoft.SharedStepCategory" name="Shared Step Category">
      <DEFAULTWORKITEMTYPE name="Shared Steps" />
   </CATEGORY>
   <CATEGORY refname="Microsoft.TestCaseCategory" name="Test Case Category">
      <DEFAULTWORKITEMTYPE name="Test Case" />
   </CATEGORY>
</cat:CATEGORIES>

Element Information

Namespace	https://schemas.microsoft.com/VisualStudio/2008/workitemtracking/categories
Schema Name	Categories
Validation File	Categories.xsd
Element Type	CATEGORIES, CATEGORY, DEFAULTWORKITEMTYPE, WORKITEMTYPE
Can Be Empty	Yes

Category Schema Definition

The following code lists the schema definition for the categories work item tracking object:

<?xml version="1.0" encoding="utf-8" ?> 
<xs:schema targetNamespace="https://schemas.microsoft.com/VisualStudio/2008/workitemtracking/categories"
  elementFormDefault="unqualified"
  attributeFormDefault="unqualified"
  xmlns="https://schemas.microsoft.com/VisualStudio/2008/workitemtracking/categories"
  xmlns:xs="http://www.w3.org/2001/XMLSchema"
  xmlns:typelib="https://schemas.microsoft.com/VisualStudio/2005/workitemtracking/typelib">  
  <xs:import namespace="https://schemas.microsoft.com/VisualStudio/2009/workitemtracking/typelib"/> 
  <xs:element name="CATEGORIES">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="CATEGORY" minOccurs="0" maxOccurs="unbounded">
          <xs:complexType>
            <xs:sequence>
              <xs:element name="DEFAULTWORKITEMTYPE" type="WorkItemTypeRef" />
              <xs:element name="WORKITEMTYPE" type="WorkItemTypeRef" minOccurs="0" maxOccurs="unbounded"/>
            </xs:sequence>
            <xs:attribute name="refname" type="typelib:ReferenceName" use="required"/>
            <xs:attribute name="name" type="typelib:FriendlyName" use="required"/>
          </xs:complexType>
          <xs:unique name="WorkItemTypeName">
            <xs:selector xpath="*"/>
            <xs:field xpath="@name"/>
          </xs:unique>
        </xs:element>
      </xs:sequence>
    </xs:complexType>
    <xs:unique name="CategoryRefName">
      <xs:selector xpath="CATEGORY"/>
      <xs:field xpath="@refname"/>
    </xs:unique>
    <xs:unique name="CategoryName">
      <xs:selector xpath="CATEGORY"/>
      <xs:field xpath="@name"/>
    </xs:unique>
  </xs:element>
  <xs:complexType name="WorkItemTypeRef">
    <xs:attribute name="name" type="typelib:NonEmptyPlainConstant" use="required"/>
  </xs:complexType>
</xs:schema>

See Also

Tasks

Create a Category for Types of Work Items

Other Resources

Grouping Work Item Types into Categories