Share via

Naming Conventions for Work Item Tracking Objects

  • Article

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.

Category

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

  • Friendly Name Requirements

  • Reference Name Requirements

  • Field Reference Names and Portability Requirements

  • Examples of Field Reference Names

Friendly Name Requirements

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.

Reference Name Requirements

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 (--).

Field Reference Names and Portability

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.

Examples of Field Reference Names

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

System Namespace Examples

System.Id

System.Title

System.CreatedBy

System.CreationDate

System.ChangedBy

System.ChangedDate

System.State

System.Reason

Microsoft Namespace Examples

Microsoft.Common.Status

Microsoft.Common.Priority

Microsoft.Scheduling.Duration

Microsoft.Scheduling.PercentComplete

Microsoft.Testing.TestCaseName

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:

TreyResearch.Common.Severity

TreyResearch.Common.Phase

TreyResearch.RiskManagement.RiskType

TreyResearch.RiskManagement.Resolution

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

A_Datum.Common.BusinessPriority

A_Datum.Bug.FoundInPhase

A_Datum.Bug.FixInPhase

See Also

Reference

FIELD (Definition) Element

Concepts

Customizing Project Tracking Data, Forms, Workflow, and Other Objects