Project Summary:
To align with the changes being made to the field configuration model , we will update the existing Create Project API as well.
We’re looking for feedback from users to ensure these proposed changes align with how users currently use the existing Create Custom Project API, and to determine whether the new payload changes can fully replace the existing API.
-
Publish: March 2026
-
Discuss: Start of open beta at end of January 2026
-
Resolve: TBC end of Open Beta
Problem:
As part of the changes to the field configuration model referenced above, we’re replacing Field Configurations (FieldLayouts) entirely. However currently, the Create custom project API requires project details and capabilities, including Field configurations(fieldLayout) and Field configuration schemes (fieldLayoutScheme).
In this RFC we will:
-
detail the upcoming changes to the Create custom project API
-
outline the transition plan, and
-
explain how these updates affect API consumers
Proposed Solution:
Our proposed changes, which are detailed below, replace the legacy Field Configuration Scheme (fieldLayoutScheme) and Field configuration (fieldLayout) in API payload.
These changes will be rolled out gradually. Both models will be supported during the transition, after which, we’ll deprecate fieldLayoutScheme and fieldLayout.
Key Milestones:
January : The new Fields configuration model enters Open Beta period
-
We’ll begin the transition: As the new model begins its rollout, both models will be accepted.
-
References in the payload to field configuration scheme ID (
fieldLayoutSchemeId), field configuration scheme (fieldLayoutScheme), and field configuration (fieldLayout) will be deprecated. Spaces created with the existing payload will not be impacted. -
A new payload using the Field scheme will be available. Spaces created with the new payload will produce a Field scheme.
-
Proposed change to update the Create custom project API: If a reference to the old model’s field configuration scheme (
fieldLayoutSchemeId) is provided, our suggested change is to create a new Field scheme instead of keeping the old ID as a direct reference.
March/April: The new Fields configuration model rolls out to all customers
- Customers are encouraged to onboard to the new model before the old model is deprecated. New spaces with the new model will start producing Field schemes instead of using the old model.
June
fieldLayoutSchemeandfieldLayoutwill no longer be supported.
Create custom project REST API
POST /api/{v:2|3|latest}/project-template
Creates a space based on a custom template provided in the request.
Existing Payload
"template": {
"field": {
...
"fieldLayouts": [
{
"pcri": "pcri:fieldLayout:ref:10001",
"name": "Field Layout for {{project.key}}",
"description": "This is the field layout for {{project.key}}",
"configuration": [
{
"pcri": "pcri:field:id:summary",
"show": true,
"required": true
}
]
}
// ...
],
"fieldLayoutScheme": {
"pcri": "pcri:fieldLayoutScheme:ref:newFieldLayoutScheme",
"name": "Field Configuration Scheme for Project {{project.key}}",
"description": "This Field Configuration Scheme was generated for Project {{project.key}}",
"defaultFieldLayout": "pcri:fieldLayout:ref:10001",
"explicitMappings": {
"pcri:issueType:ref:10001": "pcri:fieldLayout:ref:10002",
"pcri:issueType:ref:10002": "pcri:fieldLayout:ref:10003"
}
}
}
}
New Payload
Capabilities fieldLayouts and fieldLayoutScheme are replaced by fieldAssociationScheme.
We are considering introducing a new concept new in the payload.
- QualifierType and QualifierId – a way to express the scope of a field association (for all issue types or a specific issue type).
Within fieldAssociationScheme.items, qualifierType and qualifierId together define where a field association applies.
-
qualifierType – scope type
-
All issue types:
pcri:qualifierType:id:base -
A specific issue type:
pcri:qualifierType:id:issueType
-
-
qualifierId – the scoped entity
-
When qualifierType is base (all issue types): qualifierId must be
null -
When
qualifierTypeis issueType (single issue type): qualifierId must be the PCRI of that issue type, e.g.pcri:issueTypeId:id:10001
-
"template": {
"field": {
...
"fieldAssociationScheme": {
"pcri": "pcri:fieldAssociationScheme:ref:newFieldAssociationScheme",
"name": "Field Association Scheme for project {{project.key}}",
"description": "This Field Association Scheme was generated for Project {{project.key}}",
"projectPcri": "pcri:project:ref:newProject1",
"items": [
{
"pcri": "pcri:fieldAssociationItem:ref:fieldAssociationItemRef1",
"qualifierType": "pcri:qualifierType:id:base",
"qualifierId":null,
"description": "Summary field for all issue types",
"required": true,
"rendererType": "jira-text-renderer"
},
{
"pcri": "pcri:fieldAssociationItem:ref:fieldAssociationItemRef2",
"qualifierType": "pcri:qualifierType:id:issueType",
"qualifierId": "pcri:issueTypeId:id:10001",
"description": "Custom field for Bug issue type",
"required": false,
"rendererType": "default"
}
],
"onConflict": "USE"
}
}
}
Asks
Early access and feedback
We are seeking feedback to understand how users are currently using the existing Create custom project API, and to determine whether the new payload changes can fully replace the existing API.
If you’d like to join, fill out an expression of interest here.
Affected APIs
Project Create
