Naming conventions for work item tracking objects

In Visual Studio Team Foundation Server (TFS), all work item tracking objects are associated with one or more names. Most have friendly display names and all, except work item types and global lists, are associated with reference names. A friendly name is a unique, user-visible identifier for a field. Using friendly names ensure consistency across all team projects and work item types in a project collection. TFS uses the reference name internally and you cannot change it 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.

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 work item tracking fields. These fields are defined in a work item type definition of the TFS process templates. TFS does not prevent you from creating your own Microsoft.X field. However, this practice is strongly discouraged because it might impede Team Foundation Server TFS functionality or the ability for the Configure Features wizard to successfully update a team project after a TFS upgrade.

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

For descriptions of system fields and fields defined in the TFS process templates, see Work item field reference for Visual Studio ALM.

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 reference

Concepts

Customize work tracking objects to support your team's processes