The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

Naming Conventions for Work Item Tracking Objects

All work item tracking objects are associated with one or more names. Most have friendly display names and all but work item types and global lists are associated with reference names. A friendly name is a unique, user-visible identifier for a field that you use to ensure consistency across all team projects and work item types in a project collection. The reference name is used internally by Team Foundation Server and cannot be changed after it is defined.

The following table summarizes the naming requirements that must be met for each work item tracking object.

Work item tracking object

Reference name

Friendly name

Work item type

Not applicable

The name of each work item type can have up to 255 Unicode characters and must be unique within a team project.

Work item field

Required. See Reference Name Requirements.

Field names can be up to 128 Unicode characters long and must be unique within a team project collection.

Link type

Required. See Reference Name Requirements.

You define two friendly names for each link type: Forward Name and Reverse Name. These names can be up to 128 Unicode characters long and must be unique for all link types defined for a team project collection.


Required. See Reference Name Requirements.

Category friendly names can be up to 128 Unicode characters long and must be unique within a team project.

Global list

Not applicable

The name of each global list can have up to 254 Unicode characters and must be unique within a team project collection.

Topic Contents

In addition to the requirements summarized in the table listed previously in this topic, the friendly names you define should meet the following requirements:

  • Names must not be empty.

  • Names cannot have leading or trailing white spaces.

  • Names cannot contain backslash (\) characters.

  • Field names cannot contain the following characters: backslash (\), period (.), and opening and closing square brackets ([]).

  • Names cannot contain two or more consecutive white spaces.

You must define a reference name whenever you add or create a work item field, link type, or category. All reference names can be up to 70 Unicode characters long.

You can define a reference name by using alphanumeric characters, underscore characters, and hyphen characters. Each reference name must contain at least one period (.), but no period can appear at the start or end of a name. A reference name cannot start with a number or an underscore, and it cannot have multiple consecutive hyphens, such as (--).

The work item type definition language includes the concept of a field reference name. Field reference names can help you to port definitions between Team Foundation project collections and also to allow third party integrations to find and refer to specific fields. These names are globally unique, just as a namespace in the .NET Framework application is globally unique.

Field reference names cannot be renamed. If, for example, you changed the field name "Title" to "Header", the field reference name of that field remains the same. Integrations and internal representations of fields should use the field reference name instead of depending on the field name itself.

The System namespace is used only to define all core system fields that are mandatory for Team Foundation system functions. Team Foundation Server prevents you from creating your own System.X field because it might impede Team Foundation Server functionality.

The Microsoft namespace is used to define fields that are defined in a work item type definition of a Microsoft Solutions Framework (MSF) process template. Team Foundation Server does not prevent you from creating your own Microsoft.X field. However, this practice is strongly discouraged because it might impede Team Foundation Server functionality

Customers and partners can create their own field namespaces for custom work item types.

For descriptions of system fields and fields defined by the MSF for Agile Software Development - v5.0, see Using System Fields and Fields Defined by the MSF Process Templates.

The following examples show valid field reference names, in various namespaces.

System Namespace Examples









Microsoft Namespace Examples






Examples in Other Namespaces

Customers and partners can also define their own namespaces to support their custom work item types. For example, the fictitious company Trey Research might define the following custom work item types:





The fictitious software company A. Datum Corporation might define the following work item types:




Was this page helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

© 2014 Microsoft