RFC-103: Jira Field Configuration Overhaul: Admin Experience and API Changes

General Request for Comments (RFC)
, , ,
1

Summary of Project:

We’re making improvements to the user experience of fields as part of ongoing efforts to simplify the field configuration experience. The Field Configuration page in the Jira admin section is one of the important admin experiences. However, we discovered that this current admin experience is not easy and is confusing to use. To support the experience changes, our team will be working on an architectural change as detailed in this RFC.

  • Publish: December 2025
  • Discuss: During early access starting at 1st October 2025
  • Resolve: TBC end of early access

Problem

To improve the admin experience, we are making architectural changes to how fields are handled in Jira.

Currently, admins create groups of fields called Field configurations which can be combined into Field Configuration Schemes. Field Configurations can be assigned directly to specific work types within a Field Configuration Scheme, overriding the configuration set for the default mapping in that scheme. To ensure a field appears for all work types in a project, you need to add it to every Field Configuration used in the scheme—both the default and those mapped to individual work types.

With this change, we’re eliminating Field Configurations entirely which means that:

  • fields will be directly associated with Field schemes, which are used by projects. You can then limit a field to a work type within the project settings.
  • users can no longer restrict a field to a project by deleting its global context and replacing it with a project-limited one. For a field to only show in one project, that project needs to use its own scheme. The project setting in a context can only determine which variant of a field shows (such as a different list of options or default values). More about field contexts

Proposed Solution

As a result of these changes, the existing APIs for field configurations will be deprecated. We will provide alternative APIs to support the new field scheme:

  • Reading Fields: These APIs allow users to access fields available in a given project and issue type without requiring admin permissions. More details can be found here.
  • Updating Configuration: Admin-level APIs enable the backup and restoration of configurations, allowing for efficient management of field settings. More details can be found here.

Asks

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.
  • how users are using issue custom field contexts to associate fields to specific projects and whether the new APIs can be used instead for this operation.

If you’d like to join, fill out an expression of interest form here.

Affected APIs

Field Configuration

Issue Custom Field Contexts

Issue Custom Field Contexts APIs aren’t impacted directly by these changes, but reference field associations defined by the field configurations. Users will no longer be able to restrict a field to a project by deleting its global context and replacing it with a project-limited context.

1 Like
2

@LeanneWon These two links refer to the same RFC-105. One of them should probably link to RFC-104?

Also, the “Affected APIs” in this post list the “Issue Custom Field Contexts” APIs, yet the two other RFCs don’t reference those at all. Are they missing from RFC-104 and RFC-105 or should they be discussed in here? Or are they not affected at all?

Since we’re using almost all of the APIs listed in this post, we appreciate these RFCs to be as precise as possible. Thank you!

3 Likes
3

@BenRomberg Thanks for pointing that out. I have updated the posting so it uses the correct link.

There are 2 separate RFCs for Field Configuration APIs as these APIs are directly impacted by new conceptual model and as a solution, we are proposing new set of APIs that will potentially replace them.

For “Issue Custom Field Contexts” APIs, these APIs are not impacted as their contract is staying the same. However, they are listed as affected APIs because the changes to the field configuration domain will alter the expectations regarding field associations. Users will no longer be able to restrict a field to a project by deleting its global context and replacing it with a project-limited context.

I also have updated the RFC to be more clear on this point.

2 Likes
4

Hi, I’ve looked at these but can’t see a way of getting the allowed values of a field. Is there a plan to add this?

Regards

Paul

5

Hi @LeanneWon

  • Regarding Field Configurations can also be linked directly to specific work types, which overrides a project’s Field Configuration Scheme, could you elaborate on how this is possible in Jira Cloud? I am unaware of any possibility of linking Field Configurations to specific work types without using Field Configuration Schemes.
  • Currently, it’s really easy for multiple projects to share the same configuration for given work types, while using different configurations for other work types. To do so, they can use different Field Configuration Schemes that reference the same Field Configurations for some work types. If I understand Field Schemes correctly, this won’t be the case any more. Projects can either use the same Field Scheme and share the same configuration for all work types, or must use completely different Field Schemes. Is that accurate?
  • The two models (Field Configuration Schemes and Field Schemes) are quite different. Will customers be able to migrate their existing configuration?

Thanks!
Nico

6

Hi @paul No, we do not have allowed values as part of the API design right now. However, I am interested in understanding your use case for needing the allowed values for the fields. If you could share more details, we can review the API design to better help customers use it.

7

@LeanneWon One of our apps needs to retrieve complete Jira field details, ideally for the Create Issue screen, but all fields would be useful, so we can prompt users to provide information at a global level. This includes retrieving all allowed values for fields where applicable.

Right now, the only way to achieve this is to:

  1. Get a list of all projects.

  2. Call the Get Create Metadata REST API for each project.

This approach is slow and inefficient, especially for customers with 1,500+ projects.

I want a way to get all field details, like those included in the get create metadata REST API (including the allowed values). Even if this is only retrieved using a flag.

Regards

Paul

8

Hi @NicoFrossard

Thanks for the questions!

Regarding Field Configurations can also be linked directly to specific work types, which overrides a project’s Field Configuration Scheme, could you elaborate on how this is possible in Jira Cloud? I am unaware of any possibility of linking Field Configurations to specific work types without using Field Configuration Schemes.

Yes, you are right. My previous statement was referring to the feature where a field configuration can be linked to a specific work type, which overrides the field configuration that is linked to the default mapping. As you also stated, both are configured within the scheme. I understand the description in the RFC can be a bit confusing, and I will update it so it explains this correctly.

If I understand Field Schemes correctly, this won’t be the case any more. Projects can either use the same Field Scheme and share the same configuration for all work types, or must use completely different Field Schemes. Is that accurate?

Yes, that is correct. In Field Schemes, there isn’t a concept of sharing a Field Configuration directly between work types. To better understand your needs, could you share how much your Field Configurations typically differ when used across multiple work types compared to the default mapping within the scheme? How are these Field Configuration different from the Field Configuration linked to default work types?

With the new field scheme experience, you no longer need to link every field to each work type individually. Instead, you can specify fields that apply to all work types, and then add specific fields for individual work types as needed—these act as additional layers within the same scheme.

The two models (Field Configuration Schemes and Field Schemes) are quite different. Will customers be able to migrate their existing configuration?

Yes, customers will be able to create new Field Schemes based on the existing Field Configuration Scheme

9

@LeanneWon Thanks for the feedback!

We don’t have the use case ourselves, so I wouldn’t be able to elaborate on a specific scenario requiring to reuse Field Configurations between projects for specific work types to prevent having to manually duplicate the configuration.

I just wanted to point out that this is a feature that is most likely being used right now, and, to my understanding, would be lost with the new system.

10

Thanks for the information @paul

If I understand correctly, your use case is to retrieve all allowed values for a field across every project in the customer’s instance. This type of operation can be quite resource-intensive, even with the new API, because it requires gathering data that isn’t limited to a specific set of projects. As a result, performance may be impacted, especially in larger environments.

I’ll discuss internally how we might enhance the new read API to provide more detailed field information. In the meantime, to help ensure better performance and reliability, I recommend always scoping your requests to a defined set of projects whenever possible. This approach will help keep response times fast and reduce the risk of running into API rate or performance limits.

If you have more details about your use case or specific requirements, please share them—this will help us explore the best way to support your needs.

11

@NicoFrossard Thank you for your feedback. We understand that this change may present challenges for customers who rely heavily on sharing Field Layouts. We will be closely monitoring this during the EAP program to assess the impact and understand how significant it is for our customers. Your input is truly appreciated—thank you!

12

Hi @LeanneWon

Not just allowed values but a list of all fields, their types (for custom field) etc. The best way to describe it is the create metadata but without tying it to a project, an issue type and the create screen. Depending on your setup, it’s currently possible that the fields for the create metadata are all fields anyway. So while it isn’t trivial, it’s nowhere near the data retrieved getting the create meta data for all projects

Thanks for raising it internally. We do try to restrict request scopes but that isn’t possible when we could be setting the value of any field when creating an issue in any project. We don’t know the specific project until runtime so during configuration, we need to load everything to see what fields (and allowed values) are available

I realise that the get create meta data REST API we use was meant to be deprecated and was meant to be phased out over 12 months ago, so I know that Atlassian wants us to move on to something else. But at the moment, we don’t have anything else we can use.

The easiest definition of what I want is

  1. A list of all fields in Jira (paginated is fine)
  2. For each field, I want the same data as provided in the get create meta REST API
  3. We don’t need to know the project or screens that use the field. We can also get by without knowing if the field is on the create screen

Have a great day
Paul

13

Indeed, the current admin experience around custom fields is bad - in fact it’s the reason why we created a new set of admin pages in JMCF where users can create and manage their custom fields. We did this to streamline the process of creating the custom field, defining what projects and issues it exists in, where it is displayed, and context specific configuration settings for the field. We did this on top of the existing api’s already offered in Forge. It’s a much better experience.

So, if we could do that in our app on the existing api, why is it that Atlassian can’t fix these things within the Jira UI without breaking all the existing API’s and apps that depend on them? We know you want to improve your product and we’re on board with that but API’s are essentially contracts with the vendors and Atlassian should be doing everything possible to make those stable. The proposed api changes will cause significant effort on our part to rearchitect and rewrite code that was built and tested on fairly new api’s that Atlassian previously committed to being stable. And this practice seems to becoming more and more common as Forge picks up steam. This is very frustrating and costs us a lot in terms of development resource and lost opportunity.

Speaking as someone who’s spent the past year just trying to keep our Forge app running on the shifting runtime and API landscape I think that Atlassian should be doing a lot better job at maintaining a stable environment for applications. We want to build more apps and features for the ecosystem and not spend our time continually reworking existing apps due to platform churn.

14

Hi @jeffryan

Thank you for sharing your perspective so candidly. We absolutely understand how frustrating breaking API changes can be - especially when you’ve invested so much in delivering a streamlined experience for your users. This is exactly why we created this RFC: to open up the conversation and ensure the new APIs are designed with your needs in mind, and ultimately provide a much better experience for everyone.

Jira is evolving, and we’ve reached a point where the existing model - while it’s served us for a long time - has become too cumbersome and limiting. Making the call to introduce breaking changes wasn’t taken lightly, but it’s necessary to unlock a more flexible and robust platform for the future.

We genuinely tried to find a way to maintain backward compatibility for the existing APIs. Unfortunately, the changes required in the underlying model made this impossible. The current APIs expose too many implementation details, which limits our ability to improve Jira without further disruption. With the new APIs, we’re focused on providing better abstractions that are easier to use and will allow Jira to evolve more smoothly going forward.

We know this transition is a big ask, and we’re here to support you. If you’re able to share more about your specific use cases, it would help us better understand where the impact is greatest. We’re actively exploring whether we can keep some of the existing APIs available with limited capabilities, provided they remain compatible with the new model. That said, we want to be transparent - this won’t be possible for every API, and maintaining a partial set could introduce confusion or unintended issues down the line.

15

Hi @paul

The best way to describe it is the create metadata but without tying it to a project, an issue type and the create screen.

The challenge here is that this metadata is fundamentally tied to both project and issue type. For example, properties like:

  • hasDefaultValue
  • required
  • operations

…can all be configured differently depending on the project and issue type. It’s also important to recognise that logic around properties like required and editable will likely evolve over time - and could even vary between individual issues within the same project or issue type.

allowedValues is particularly tricky. Its values can differ by project and issue type, and it doesn’t scale well. Imagine an option field with over 100,000 possible values—returning all of that data unpaginated in an API just isn’t feasible.

The closest API we can provide would be under RFC-104: New Field Scheme Model APIs:

GET /rest/api/2/projects/fields?projectId=<array>&workTypeId=<array>&fieldId=<array>&expand=<properties> (parameters are optional)

with expands:

  • details - name / description
  • schema - type, autoCompleteUrl
  • configuration - default value and field type specific config

The response would look something like this:

{
  "isLast": true,
  "maxResults": 50,
  "startAt": 0,
  "total": 2,
  "values": [{
    "fieldId": "environment",
    "projectId": "10000",
    "workTypeId": "10001",
    "isRequired": false,
    "details": {
      "name": "Umwelt",
      "untranslatedName": "Environment",
      "description": "For example, operating system, software platform and/or hardware specifications (include as appropriate for the work).",
    },
    "schema": {
      "type": "environment",
      "value": {
        "type": "string"
      }
    }
  }, {
    "fieldId": "customfield_10000",
    "spaceId": "10000",
    "workTypeId": "10002",
    "isRequired": false,
    "details": {
      "name": "Farbe",
      "untranslatedName": "Colour",
      "description": "Select the desired colour"
    },
    "schema": {
      "type": "com.atlassian.jira.plugin.system.customfieldtypes:multicheckboxes",
      "value": {
        "type": "array",
        "autoCompleteUrl": "https://<>/rest/api/3/projects/fields/available-values?fieldId=customfield_10000&projectId=10000&workTypeId=10002",
        "items": {
          "type": "option"
        }
      }
    },
    "configuration": [{
      "defaultValue": [{
        "id": 10001,
        "label": "Purple"
      }]  
    }]
  }]
}

(this is a very early draft, we will post an update once it is finalised)

If configuration details aren’t your focus and you just need to retrieve all fields available to a specific user, you can use the following endpoint: GET /rest/api/3/field/search. This endpoint provides field details that are not tied to a project.

16

@MikhailBogdanov Thanks for getting back to me.

I could skip hasDefaultValue, required and operations, but not allowedValues. Currently, when I’m loading all projects create meta data, I just grab a single allowedValues declaration and ignore the rest. So I’m potentially missing out on some details.

Thanks for mentioning that REST API. I do need schema and details but I would still need to go back to the create meta data to get the allowed values. So, in that case, I might as well just stick with create meta.

I’ll take a look at the user field search

I may just have to try and figure a way around this.

Thanks for your reply
Paul

1 Like
17

@paul

I just grab a single allowedValues declaration and ignore the rest

I’m curious: how are you actually using those allowedValues in your workflow? The reason I ask is that we’re likely heading toward either removing them entirely or limiting them to just the “first X values.” With some of the complex data shapes we’re seeing, the current approach just isn’t sustainable.

I would still need to go back to the create meta data to get the allowed values

If we provided a separate, paginated endpoint for fetching available values, would that help solve your use case? I get that adding extra requests isn’t ideal, but it’s the most reliable way we can ensure performance at scale for these APIs.

18

Hi @MikhailBogdanov

We use them to allow users to create templates of issues that they want created. This can be at the project level (easy) or globally (what I’m having problems with). I didn’t realise that customers were using such large allowed values. Limiting it wouldn’t affect us, maybe produce less data for us to load

An endpoint would be handy, but only if I could give it a list of field ids. If we had to call it for each field id, then the number of calls would be too great. We load the create meta data in batches of 50 projects. So if a customer has 500 projects that would be 10 REST API calls.

If we had to load all fields (paginated) plus one call per field with allowedValues (possibly multiple if over page size) then that would ramp up the number of calls we would have to make (I’m not sure what the average number of fields customers have with allowed values). The rate limiting would probably stop that from happening. We are limited in the time we can spend doing this, customers want a responsive screen.

Regards

1 Like
19

@MikhailBogdanov

Specifically we depend heavily on the notion that each custom field has a context that defines project and issue type scope as well as configuration options for the custom field.

Per Jira’s current architecture, we do support multiple context’s per custom field - each with it’s own unique project/issue scope and configuration. The custom field ID and context ID form a heavily used partition key within our app and we store these in various places within forge storage, the forge cache, and in events that stream through the Async Event Queues. We use those Id’s to access related context scope and configuration data in many application processes.

Most users however find the concept of multiple contexts per custom field confusing and difficult to manage. As a result, we don’t really promote that behavior in our UI and instead we simply encourage the user to create a new custom field. During the creation process we ask the user to define the field name and type, the project/issuetype scope, screens, and any additional configuration options for that field type. Then via api we create the field and update the context that jira created to match the users scope and configuration choices.

We wouldn’t be sad to see multiple contexts per custom field go away as long as the existing custom fields that are currently configured that way are migrated effectively to multiple custom fields. This might be problematic though as the customFieldID would change and users might be relying on that somewhere else.

And while we generally steer people to select specific projects and issue types of the context, we do still let the user select AllProjects and AllIssueTypes for these settings as some users want the field to exist in all current and future issues. Many customers use this so we wouldn’t want to see the global scope option go away.

Given that our app provides a streamlined path through the entire custom field creation and management process, you can imagine that we use a lot of the api’s that you plan to deprecate. So it’s a big hit to us on both the front end UI’s and the backend processing of the app where we perform the calculations.

There are also the significant matters of rollout and migration. We want to understand more details on how this will work to ensure it will be a seamless process for our users with no data loss. Existing custom fields should continue to calculate without disruption and the configurations and scopes defined for those fields should continue to be honored. Given the magnitude of these changes, we will require a good deal of overlap between rollout of the new api’s and deprecation of the old ones. Since we store and depend on the context and configuration ID’s there may also be need for some sort of migration hooks to bring that data inline with the new architecture.

I know this is hard. Building stable api’s requires significant effort and foresight - and even the best laid plans change. We do appreciate that you’re using the RFC process to bring changes like this forward. The business always wants us to charge ahead as fast as possible but gathering input and feedback ahead of time is alway way better than trying to patch up a mess later. So thanks a lot for publishing this RFC and responding to our input.

2 Likes
20

@jeffryan

Thanks for your detailed response - really appreciate the depth of your feedback!

To clarify: we’re not removing the concept of multiple contexts per field. In fact, we’re looking to expand it, enabling multiple configurations per project in the future. The heart of these changes is to create a single source of truth for “fields available in a given context.” Right now, Jira’s architecture requires both context and field layout scheme alignment to enable a field, which leads to confusion and friction.

Here’s how the new model will work:

  • Configuration context: This will handle default values, options, and other field-type-specific parameters. Based on our data, most fields will only need a single default configuration.

  • Field scheme: This defines which fields are available and their required status. Think of schemes as collections of fields that can be shared across projects. For example, all projects owned by a given team could share the same scheme to ensure data quality and consistency.

With this approach, the field scheme becomes the go-to place for customers to see which fields are available in a given context. This is especially important as we roll out new data limits and guardrails (Data limits and guardrails | Atlassian Support).

Given the magnitude of these changes, we will require a good deal of overlap between rollout of the new api’s and the deprecation of the old ones

We’re still shaping the rollout plan and will adjust based on early access feedback. Right now, we’re aiming for a six-month transition period where customers can choose to move some projects to the new model or stick with the old one. Old APIs will continue to work for projects that haven’t switched.

At the end of the transition period, we’ll migrate any remaining projects to the new model and retire the old APIs.

The custom field ID and context ID form a heavily used partition key within our app and we store these in various places within forge storage, the forge cache, and in events that stream through the Async Event Queues. We use those Id’s to access related context scope and configuration data in many application processes

The current changes shouldn’t disrupt this logic - context and custom field IDs will remain the same. Future changes to the configuration context might have some impact, but our goal is to keep things as backward compatible as possible.

Given that our app provides a streamlined path through the entire custom field creation and management process, you can imagine that we use a lot of the api’s that you plan to deprecate.

It’s true - because your app offers such advanced features, it relies deeply on the underlying data model. With that in mind, here are a few suggestions based on what you’ve shared:

  • You can largely keep your configuration context logic as is, but it’s worth preparing for a future where configuration overrides are the norm, rather than isolated configs.

  • For associations, you’ll want to pivot to field schemes. You could either prompt users to select schemes for new fields, or stick with “which projects?” and map those to their schemes behind the scenes.

the configurations and scopes defined for those fields should continue to be honoured

This is a bit nuanced:

  • Existing configuration contexts will still be used to pull required configs (like options).

  • They’ll be considered during the automatic conversion from old to new schemes at the end of deprecation.

  • However, for projects switched to the new model, fetching a list of fields will no longer depend on the configuration context being defined.

A few extra tips:

  • Having many configuration contexts can hurt Jira’s performance - this is one of the differences between Cloud and Server.

  • We recommend reusing fields across projects instead of creating unique ones for each project. Too many fields can impact performance and cross-project features like automation, search, and roadmaps.