Summary of Project:
- Publish: December 2025
- Discuss: During early access starting at 1st October 2025
- Resolve: TBC end of early access
Problem
With the changes our team is making to the field configuration model, we’ll be replacing existing APIs to be compatible with our new model.
This RFC provides new APIs that perform any read and write operations that support backup and restoration of configurations.
Proposed Solution
Field Scheme APIs
1. Get Field Schemes
GET /rest/api/2/fieldscheme
Returns field schemes for scheme id provided.
Query parameters:
startAt
(integer)maxResults
(integer)id
(array)
Response:
{
"isLast": true,
"maxResults": 10,
"startAt": 0,
"total": 3,
"values": [
{
"id": "10000",
"name": "Field Scheme for Bugs",
"description": "This field scheme is for bugs only."
},
{
"id": "10001",
"name": "Field Scheme for software related projects",
"description": "We can use this one for software projects."
},
{
"id": "10002",
"name": "Field Scheme for Epics",
"description": "Use this one for Epic work type."
}
]
}
2. Create Field Scheme
POST /rest/api/2/fieldscheme
Creates field scheme with name and description provided via request body.
Request:
{
"description": "My field configuration description",
"name": "My Field Scheme"
}
Response:
{
"description": "My field configuration description",
"id":"10001",
"name": "My Field Scheme"
}
3. Update Field Scheme
PUT /rest/api/2/fieldscheme/{id}
Updates existing field scheme with name and description provided via request body.
Path parameters:
id
(integer)
Request:
{
"description": "We can use this one for software projects.",
"name": "Field Scheme for software related projects"
}
4. Delete Field Scheme
DELETE /rest/api/2/fieldscheme/{id}
Deletes existing field scheme for the scheme id provided.
Path parameters:
id
(integer)
5. Get Field Scheme to Project Mapping
GET /rest/api/2/fieldscheme/project
Returns field scheme id to project ids mapping.
Query parameters:
startAt
(integer)maxResults
(integer)projectId
(array)
Response:
{
"isLast": true,
"maxResults": 50,
"startAt": 0,
"total": 5,
"values": [
{
"fieldScheme": {
"id":"10002",
"name": "Field Scheme for software related projects",
"description": "We can use this one for software projects."
},
"projectIds": [
"10000",
"10001",
"10002"
]
}
]
}
6. Update Field Scheme for Project
PUT /rest/api/2/fieldscheme/project
Updates field scheme id for the project id provided.
Request:
{
"fieldSchemeId": "10000",
"projectId": "10000"
}
Field Scheme Item APIs
7. Get Field Scheme Items
GET /rest/api/2/fieldscheme/{id}/fields
Returns field’s configuration and mapping to work types, such as isRequired
or description
. The field id filter is optional.
Path parameters:
id
(integer)
Query parameters:
startAt
(integer)maxResults
(integer)fieldId
(array)
Response:
{
"isLast": true,
"maxResults": 50,
"startAt": 0,
"total": 5,
"values": [
{
"fieldId": "customfield_10000",
"parameters": {
"10010": {
"isRequired": false,
"description": "Special description for work type 10010"
},
"10011": {
"renderer": "wiki-renderer"
},
"default": {
"isRequired": true,
"renderer": "text-renderer",
"description": "Default description"
}
}
},
{
"fieldId": "customfield_10001",
"parameters": {
"default": {
"description": "Special description for issue type 10010",
"isRequired": true,
"renderer": "wiki-renderer"
}
}
}
]
}
8. Update Field Associations
PUT /rest/api/2/fieldscheme/{id}/fields/association
Updates field’s association for given scheme id and work types. Supports ADD
, REPLACE
, and REMOVE
operations.
*ADD
operation adds given work type mapping on top of what is already configured for the field.
*workTypes
are optional and if not provided, fields are added to default mapping. If one or more REMOVE
are provided, fields are added to specific work type.
*REPLACE
operation works as PUT and replaces existing mapping with what is provided in the request
*REMOVE
operation removes provided work type mapping of the field
workTypes
are optional and if not provided, fields are removed from default mapping. If one or moreworkTypes
are provided, fields are removed from specific work type.- Removing a field from any work type removes existing parameters attached to it.
Path parameters:
id
(integer)
Request Example:
{
"values": {
"customfield_10000": {
"type": "ADD"
},
"customfield_10001": {
"type": "ADD",
"workTypes": [
"10010", "10011"
]
},
"customfield_10001": {
"type": "REPLACE",
"workTypes": [
"10010", "10011"
]
},
"customfield_10021": {
"type": "REMOVE"
}
}
}
Request Example 2:
{
"values": {
"customfield_10001": {
"type": "ADD",
"workTypes": [
"10010", "10011"
]
},
"customfield_10001": {
"type": "REPLACE",
"workTypes": [
"10010", "10011"
]
},
"customfield_10021": {
"type": "REMOVE",
"workTypes": [
"10011"
]
}
}
}
9. Update Field Parameters
PUT /rest/api/2/fieldscheme/{id}/fields/parameters
Updates field’s parameter mapping for given scheme id and work types. This is a PUT operation which replaces what’s inside mapping
.
Path parameters:
id
(integer)
Request:
{
"values": [
{
"field_id": "customfield_10000",
"workTypes": {
"10011": {
"description": "Special description",
"remove": [
"isRequired"
]
}
}
},
{
"field_id": "customfield_10002",
"workTypes": {
"10012": {
"description": "Special description"
}
}
},
{
"field_id": "customfield_10001",
"workTypes": {
"10012": {
"description": "Special description"
},
"default": {
"description": "Special description for work type 10010",
"isRequired": false
}
}
}
]
}
Use Cases & Examples
Field Association Use Cases
Use Case | |
---|---|
Associate fields to all or specific work types | For scheme 10001 , associate customfield_10000 to all work types and customfield_10001 to work types 10010 and 10011 . |
Request:
{
"values": {
"customfield_10000": { "type": "ADD" },
"customfield_10001": { "type": "ADD", "work_types": ["10010", "10011"] }
}
}
Use Case | |
---|---|
Add association to new work types, keep existing | For scheme 10001 , associate customfield_10001 to new work type 10012 and keep existing. |
Request:
{
"values": {
"customfield_10001": { "type": "ADD", "work_types": ["10012"] }
}
}
Use Case | |
---|---|
Replace association with new work types | For scheme 10001 , associate customfield_10001 only to work type 10012 (removes others). |
Request:
{
"values": {
"customfield_10001": { "type": "REPLACE", "work_types": ["10012"] }
}
}
Use Case | |
---|---|
Remove association from specific work types | For scheme 10001 , unassociate customfield_10001 from work type 10012 . |
Request:
{
"values": {
"customfield_10001": { "type": "REMOVE", "work_types": ["10012"] }
}
}
Use Case | |
---|---|
Remove association from scheme completely | For scheme 10001 , unassociate customfield_10001 from the scheme. |
Request:
{
"values": {
"customfield_10001": { "type": "REMOVE" }
}
}
Field Parameters Use Cases
Use Case | |
---|---|
Update description and make required for a work type | For scheme 10001 , update customfield_10000 to set description and make required for work type 10011 . |
Request:
{
"values": [
{
"fieldId": "customfield_10000",
"workTypes": {
"10011": {
"description": "Special description",
"isRequired": true
}
}
}
]
}
Use Case | |
---|---|
Update description and remove required configuration | For scheme 10001 , update description and remove required for customfield_10000 on work type 10011 . |
Request:
{
"values": [
{
"fieldId": "customfield_10000",
"workTypes": {
"10011": {
"description": "Updated description",
"remove": ["isRequired"]
}
}
}
]
}
Use Case | |
---|---|
Update multiple work type configurations | For scheme 10001 , update customfield_10001 : 1. Set description for work type 10012 2. Make optional and set description for default mapping |
Request:
{
"values": [
{
"fieldId": "customfield_10001",
"workTypes": {
"10012": { "description": "Special description" },
"default": { "description": "Special description for work type 10010", "is_required": false }
}
}
]
}
Early access and feedback
We want to gather the feedback to understand how users are using existing field configuration API and whether the new API can replace the existing APIs
If you’d like to join, fill out an expression of interest form here.
Affected APIs
These APIs will no longer available to use after the existing field configuration model is fully deprecated.
The following APIs allows users to fetch or update field configuration, field configuration scheme, items and mappings.
- Get all field configurations
- Create field configuration
- Update field configuration
- Delete field configuration
- Get all field configuration schemes
- Create field configuration scheme
- Update field configuration scheme
- Delete field configuration scheme
- Get field configuration schemes for projects
- Assign field configuration scheme to project
- Get field configuration issue type items
- Get field configuration items
- Update field configuration items
- Assign issue types to field configurations
- Remove issue types from field configuration scheme