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