Announcing project/fields association improvements for company-managed projects

[JamesPetty]

Updated 14th May 2025 to include additional information on changes impacting work types and the rollout of automatic optimization of field configuration schemes.

Summary

In order to deliver reliable performance for Jira we need to make changes to how fields and work types are associated with projects, and improve how admins manage these associations.

Change	Date
1. Field Configuration Schemes will be automatically optimized	Jun 16 - Jun 30, 2025
2. Introducing the ability to add and remove fields within Field Configuration Schemes	Jun 30, 2025
3. Introducing streamlining tools to optimize field associations and work types	Jun 30, 2025
4. All new fields will need to be added to projects explicitly when created via API	Jan 1, 2026
5. Creating a work type will no longer add it to the default Work Type Scheme	Jan 1, 2026
6. Work type schemes that are associated with a project can no longer be deleted	UI: Jun 1, 2025 API: Jan 1, 2026
7. Allowing to remove work types from the Default work type scheme	Jun 1, 2025

What’s changing

1. Field Configuration Scheme optimization

In June unused fields will be automatically removed from all schemes for all customers. Pruning reduces the number of fields associated with schemes by removing any fields which meet this criteria:

• Do any work items have values for the field?
• Is the field visible on any screen/layout in the project?
• Is the field hidden on the field configuration? (hidden fields will stop being displayed)

Fields that are not used will be automatically removed in order to significantly improve the performance of Jira.

2. Adding and removing fields from Field Configurations

We’re introducing the ability to add and remove fields from field configurations:

• Removing a field from a field configuration functions similarly to hiding it, making it unavailable to projects associated with the field configuration scheme. One distinguishable difference is that when a field is removed, its configurations (e.g. descriptions) are not retained and will need to be re-entered if the field is re-associated.
• Adding a field to a field configuration is similar to showing/unhiding a field. It becomes available to the projects associated with the field configuration scheme.

Field associations can be managed via the admin UI or using the new field association REST API.

3. Streamlining tools

Tooling will be available to Jira administrators to assist with reducing the fields associated with field configuration schemes and optimising work type schemes. The new tools will allow admins to:

• Identify and remove all unused fields with a single click
• Create a new optimized field configuration scheme for a single project
• Identify unused work types per project for safe removal
• Split an work type scheme into a new optimized scheme

Using the streamlining tools should result in a noticeable performance improvement, particularly for tenants with a lot of custom fields or work types. We recommend performing streamlining as soon as possible.

4. Explicit association of new fields

New fields created via API from January 2026 will no longer be automatically associated with all field configuration schemes. They’ll need to be explicitly added to a field configuration scheme to be considered available for use within projects using the scheme.

5. New work types not added to default work type scheme

Work types created from January 2026 will not be added to the default work type scheme. They will need to be associated to the schemes for the projects where they are required.

6. Work type schemes associated with projects can’t be deleted

From June 2025 work type schemes will need to be un-associated with any projects before they can be removed from the Jira admin interface. This change will be applied in the APIs from January 2026.

7. Removal of work types from default work type scheme

We are adding the ability to remove work types from the default work type scheme. Giving better control of which work types are associated with each project.

Affected APIs

Changes are being made to the following APIs (deprecation notices with effective dates will be published):

• Get field configuration items: the isHidden property will ultimately be removed and previously hidden items will no longer be returned.
• Update field configuration items: requests with isHidden=true being set will result in a field association being removed if it currently exists. There is also a new Remove associations API.
• Edit issue: overrideScreenSecurity=true will no longer allow updating of fields that are not associated with the corresponding project.
• Replace issue field option: overrideScreenSecurity=true will no longer bypass field association checks.
• Create custom field: will no longer implicitly associate the field with all projects. It needs to be associated with the required contexts using the Create associations API.
• Create work type: will no longer implicitly associate the new work type with the Default work type scheme. Use the Associate work type to a work type scheme API to associate explicitly.
• Delete work type scheme: will return a validation error if the scheme is associated to one or more projects. Use Get work type scheme API (with the projects expand, and id query parameter) to get a list of projects. Next, use Assign work type scheme to a project API to associate all projects to another scheme and finally delete the unused scheme.
• Remove work type from work type scheme: allows to modify the Default work type scheme. Accordingly, the Add work types to work type scheme API also allows adding.
• Consequently, the Get work type scheme items API no longer guarantees that the Default work type scheme contains all work types.

Why the changes

Currently global fields are considered associated with every company-managed project, unless they have been hidden by an admin or have a scoped context.

Given that our APIs return much of a work item’s data by default, the payloads returned by our APIs are getting bigger, to the point where we see OOM (out of memory) errors on the Jira Cloud platform. The growing payloads are impacting the reliability of all of the systems involved. For example, it can increase response time when calling endpoints and result in rate limiting.

Therefore, we’re introducing mechanisms to reduce the number of fields associated with company-managed projects, without degrading the user experience.

Early access and feedback

We will be running an early access program for those changes so that you can test them ahead of time and provide your feedback.

Fill in our expression of interest form to register.

[AndreasEbert]

@JamesPetty, thanks for the info. I have two feedback items:

First:

@JamesPetty

4. Explicit association of new fields

New fields created via API from January 2026 will no longer be automatically associated with all field configuration schemes. They’ll need to be explicitly added to a field configuration scheme to be considered available for use within projects using the scheme.

To clarify (maybe my Jira knowhow is rusty): Aren’t fields added to Field Configurations, and not to Field Configuration Schemes? Afaik, in a scheme each work type is associated with a Field Configuration (and the scheme itself associated with a project), and the Field Configuration contains fields and their relevant settings. It that’s the case, please update that paragraph.

Second:
How exactly does the new Create associations API work? Does it add fields to Field Configurations, or projects to the field’s contexts, or both? Thanks for clarifying.

[ChristianCzaia]

It’s not only that specific paragraph…the mix of scheme vs. field config can be found throughout the entire article

[JamesPetty]

Hi @AndreasEbert, you are correct, fields are added to Field Configurations, not directly to the scheme themselves. When referring to the fields associated with a Field Configuration Schemes, all Field Configurations that belong to the scheme will be affected. I will review the post to clarify this where needed.

The new create associations API allows adding fields to field configurations. That API doesn’t support adding projects to a different Field Configuration, Assign field configuration scheme to project can be used for that.

[AndreasEbert]

@JamesPetty, thanks for the feedback so far. That clarifies some points.

One other thing: What about a Forge app’s custom fields? Those fields are automatically created, by Forge (I guess). Are they also affected by this change? I.e. will they also not be implicitly associated with all projects anymore when they are created by Forge in a Cloud site?

[AndreasEbert]

@JamesPetty, did you have a chance to look into my follow-up question regarding Forge customfields yet? That question is still open.
(@mpaisley, maybe you can help also – I see you’re active in Forge topics.)

[david.pinn]

The specification for the PUT /rest/api/3/field/association request is imprecisely documented.

However, the example is somewhat helpful. Here’s the sample body data provided in the API documentation:

var bodyData = `{
  "associationContexts": [
    {
      "identifier": 10000,
      "type": "PROJECT_ID"
    },
    {
      "identifier": 10001,
      "type": "PROJECT_ID"
    }
  ],
  "fields": [
    {
      "identifier": "customfield_10000",
      "type": "FIELD_ID"
    },
    {
      "identifier": "customfield_10001",
      "type": "FIELD_ID"
    }
  ]
}`;

The problem for me is that the sample body data doesn’t comport with the API specification. Should the identifier be an object or a string or an integer?

Here’s my feeble attempt to follow the bouncing ball. The body of my request is the stringified form of the following structure:

{
  "associationContexts" : [ {
    "identifier" : 11131,
    "type" : "PROJECT_ID"
  }, {
    "identifier" : 11126,
    "type" : "PROJECT_ID"
  }, {
    "identifier" : 11130,
    "type" : "PROJECT_ID"
  } ],
  "fields" : [ {
    "identifier" : "customfield_11278",
    "type" : "FIELD_ID"
  } ]
}

The request fails in the following unhelpful manner:

HTTP response status: 400
“Invalid request payload. Refer to the REST API documentation and try again.”

[JamesPetty]

Hi @AndreasEbert yes new Forge app custom fields (created from 1st Jan) will also be affected by this change and will need to be associated with the projects that require access. Existing Forge app fields will remain associated with current projects until removed by a Jira administrator.

[JamesPetty]

Hi @david.pinn thanks for your question. Could you try sending the identifiers as strings instead of numbers? We will update the public API documentation to make this clear.

[david.pinn]

I tried sending the identifiers as strings, but it failed in the same way as before:

Status=400, Body: {“errorMessages”:[“Invalid request payload. Refer to the REST API documentation and try again.”]}

Does it work for you? @JamesPetty

[JamesPetty]

I’ve tested with your example payload and it does work for me, regardless of whether I pass the identifier as string or number. I’d suggest raising a support ticket and we can look closer at why the request is being rejected for you specifically.

[david.pinn]

For reference, here is the JavaScript code I’m running:

    const payload = {
        associationContexts: projectIds.map(projectId => ({
            identifier: projectId,
            type: 'PROJECT_ID',
        })),
        fields: fieldIds.map(fieldId => ({
            identifier: fieldId,
            type: 'FIELD_ID',
        })),
    };
    const response = await api.asApp().requestJira(
        route`/rest/api/3/field/asssociation`,
        {
            method: 'PUT',
            headers: {
                'Accept': 'application/json',
                'Content-Type': 'application/json',
            },
            body: JSON.stringify(payload),
        },
    );

[clouless]

@JamesPetty I wanted to ask a different question. There was some thread here about the EAP early on where we were somehow promised an optimized form of query mechanism to query something like “get all fields associated for project”.
Was some field search API enriched with this functionality or are you also planning a GET endpoint where you could pass query params like projectId?

thanks.

[AndreasEbert]

@JamesPetty

yes new Forge app custom fields (created from 1st Jan) will also be affected by this change and will need to be associated with the projects that require access.

@JamesPetty, I think this will be hard to communicate to customers. For example in our Forge app: We use a customfield to store out-of-office information of a work item’s assignee. We use a customfield (instead of say, issue-properties (“work-item-properties”?)) because that’s easy to use in Automation rules where such out-of-office data should be consumed. That customfield is not intended to be put on screens, so customers usually don’t bother with configuring it. They just expect the functionality to work – i.e. for the Forge customfield to be available for a given work-item. Which won’t be the case, because they have to add it to relevant (all?) Field Configurations first.

Also, Forge customfields are locked, by design. Can locked fields be added to Field Configuration? I can see in my EAP-enabled site that they definitely cannot be removed, so maybe they also cannot be added. That would be a blocker.

Bottom line: I think Forge customfields should be handled differently than normal customfields.

(Additionally, in the new Field Configuration UI the toggle “Hide locked” doesn’t work: When enabled locked fields are still listed.)

[BarbaraSchwarzwaldDe]

Some feedback from my end.

We have a forge-only custom fields-centered app, so these changes are very relevant to us. Thanks for already getting clarification on whether this will affect forge custom fields, @AndreasEbert!

Now for some feedback/questions:

1. I see some potential for user confusion with this additional level of association between fields and projects, especially with the functionality overlap with Contexts. This will add another possible answer to the question of “why does my field not show up in my work items?”.

2. At the moment, I’m a little confused as well due to the slightly contradicting definitions:

With what exactly will fields be associated (i.e. which pairing is stored under the hood?)

• Field ↔ Field configuration? This would mean a field could be associated with some but not all work types in a project depending on the field configuration scheme.
• Field ↔ Field configuration scheme? This is what your info here mainly suggests. This means, that field configurations still at include all fields, but parts of it are ignored/irrelevant in each project depending on the field configuration scheme of that project (and the custom fields associated with it). Changing the Field configuration scheme of a project might change which custom fields show up in the work items.
• Field ↔ Project? This is what we as developers seem to be allowed to set/get via the API. But is it stored like that under the hood? In that case, I would assume that which custom fields show up stays the same, even if an admin switches out the field configuration scheme in a project.

3. How will this affect the Default User flow for customers when creating fields?

You mention that we will have to explicitly associate fields with projects when creating them with the API, but will this be reflected in the normal Custom Field User UI?

I.e. - right now, when a user creates a custom field directly via default Jira administration (native custom field, forge plugin custom field or connect plugin custom field) they just have to pick the field type and set Name and descriptions. In the background, jira creates the field with a default “all project/all issues” context and forwards the user to the “associate screens” page.

Will new fields created like that be associated to no projects (or field configurations)? All projects? Will there be an additional step/picker in the dialog for the user to “pick the projects you want to use this field in”? Does associating a field with screens affect this in any way?

4. Is this part of or will this interact with upcoming changes/overhaul of custom field contexts? (see the Mar 2025 update in this issue: https://jira.atlassian.com/browse/JRACLOUD-6851 ).
   As context already “associate” a custom field with projects in a way, there seems to be significant overlap there to me.

Regards,
Barbara

[AndreasEbert]

@JamesPetty, did you have a chance yet to look into my follow-up questions regarding Forge customfields, i.e. locked customfields? A response would be appreciated.

[JamesPetty]

Hi @david.pinn can you please double check the request URL you are hitting, from your example it is incorrect due to a typo in /asssociation, it should be /rest/api/3/field/association

[JamesPetty]

Hi @clouless the Get fields paginated API includes a projectIds filter which allows getting the associated fields for a project.

[JamesPetty]

Hi @AndreasEbert, thanks for your feedback regarding Forge app fields. We do appreciate the use case of out-of-office fields which aren’t added to screens but should still be available to automations etc. Under EFA this can still be achieved it just requires fields to be associated to the projects where they are going to be used but not necessarily added to the screens. Apps can use the field association REST API to achieve this.

Locked fields can be added to field configurations in the UI and API. We’ve fixed the issue with the hide locked filter in the UI.

Thanks again for your input, we’ll be collecting all the feedback we get for further consideration.

[david.pinn]

Thanks James.