Custom Fields in REST API
This page describes the hierarchy of custom fields in YouTrack and how the CustomField, ProjectCustomField, and IssueCustomField entities differ from each other.
CustomField
CustomField
is an entity that defines a common custom field which contains basic attributes like "name", "fieldType" and other described on the JSON Schema page. Notice that "instances" property contains setting of this field in different projects.
The following sample shows how to get custom fields. By default, YouTrack returns only $type
and id
attributes of the requested entities. To get more information about custom fields, we explicitly provide a list of returned entity attributes in the fields
parameter of the request. Notice that $type
attribute will be in response regardless of whether you specify it explicitly or not.
Sample request
Sample response body
ProjectCustomField
ProjectCustomField
entity contains settings of a CustomField
("field" attribute) in a particular project ("project"), such as the set of possible values ("bundle"), whether the field can be empty or not ("canBeEmpty") and so on. For the complete list of attributes, see the JSON Schema page.
Sample request
Sample response body
IssueCustomField
The IssueCustomField
entity contains a value ("value" attribute) of a ProjectCustomField
("projectCustomField") for particular issue. The value can be a simple one (string, integer,..), a link to an existing entity (link to particular user for Assignee field), or a collection of values (Affected versions field).
Sample request:
Sample response body:
$type Mapping for Custom Fields
The following table shows the mapping between supported issue custom fields and their corresponding $type values. You must provide the $type value in the POST request when you need to set or update a custom field in an issue.
Custom Field Type | IssueCustomField | ProjectCustomField |
---|---|---|
enum[1] | SingleEnumIssueCustomField | EnumProjectCustomField |
enum[*] | MultiEnumIssueCustomField | EnumProjectCustomField |
build[1] | SingleBuildIssueCustomField | BuildProjectCustomField |
build[*] | MultiBuildIssueCustomField | BuildProjectCustomField |
state[1] | StateIssueCustomField | StateProjectCustomField |
version[1] | SingleVersionIssueCustomField | VersionProjectCustomField |
version[*] | MultiVersionIssueCustomField | VersionProjectCustomField |
ownedField[1] | SingleOwnedIssueCustomField | OwnedProjectCustomField |
ownedField[*] | MultiOwnedIssueCustomField | OwnedProjectCustomField |
user[1] | SingleUserIssueCustomField | UserProjectCustomField |
user[*] | MultiUserIssueCustomField | UserProjectCustomField |
group[1] | SingleGroupIssueCustomField | GroupProjectCustomField |
group[*] | MultiGroupIssueCustomField | GroupProjectCustomField |
int | SimpleIssueCustomField | SimpleProjectCustomField |
float | SimpleIssueCustomField | SimpleProjectCustomField |
date | DateIssueCustomField | SimpleProjectCustomField |
date and time | SimpleIssueCustomField | SimpleProjectCustomField |
period | PeriodIssueCustomField | PeriodProjectCustomField |
string | SimpleIssueCustomField | SimpleProjectCustomField |
text | TextIssueCustomField | TextProjectCustomField |