DEV Community

Cover image for Jira field schemes replaced field configuration schemes
Mihai Perdum
Mihai Perdum

Posted on Originally published at leanzero.net

Jira field schemes replaced field configuration schemes

On 20 October 2026, Carol Low from Atlassian answered a question under the Community's field schemes FAQ, a post that had 56,420 views when I checked on 15 November. Sites on continuous release tracks already had field schemes, she wrote, and sites on bundled tracks were scheduled to get them on 10 November. (A release track is the setting that decides when Atlassian's changes reach your site.) So if you run Jira Cloud, your field configurations and field configuration schemes have most likely been converted by now, automatically, in your site's maintenance window.

We looked at what that conversion left behind on our own test site on 15 November. The new Field schemes page listed 43 field schemes for 59 company-managed spaces, and 24 of them weren't linked to any space. Meanwhile the old field configuration API still answered with HTTP 200, with numbers that no longer match the new model: 740 items in our default configuration against 471 fields in the default field scheme. Writes through the old API came back 404.

If you look after a Jira site with somewhere between 50 and 2,000 people on it, the part to worry about is the scripts and reports nobody has touched in a year. Scripts that only read won't fail. They'll read stale numbers and carry on.

A space is Jira's current name for a project, and the REST API still says project. A work type is what older screens called an issue type. Our test site is wolfaenpak.atlassian.net, which is on a Jira plan with a sandbox (Premium or Enterprise) and which we keep for exactly this kind of thing, and the numbers below come from that site after the real migration.

What we found on 15 November 2026

  1. We had 43 field schemes after the migration. 19 were linked to spaces, one of them only to a space in the trash. The other 24 were linked to none (I'll call those orphans), and all 24 were schemes for service spaces, meaning Jira Service Management spaces, that no longer exist.
  2. 42 of our 59 live company-managed spaces share the Default Field Scheme. The other 17 each have a scheme of their own, and 12 of those were made by our own test-data script through the new API.
  3. The old read endpoints still answer with HTTP 200, but the numbers don't match the new model: 740 items against 471 fields for the default, 165 against 157 for a service space, 170 against 180 for a test space.
  4. Asking the old API "which scheme does this space use" gave back an empty list for all 70 spaces, company-managed and team-managed.
  5. An old write returned 404 "The field configuration was not found." on an id that the old read still answers for. Through the new API, the same change worked once we left one setting out of Atlassian's example.
  6. Jira refused to delete the default scheme and a scheme in use, and it deleted an orphaned scheme in one call.

What Jira field schemes replaced: field configurations and field configuration schemes

Until this year, a Jira admin needed two objects to decide which fields a space shows. A field configuration listed the fields and marked each one hidden, optional or required. A field configuration scheme then mapped work types in a space to field configurations, so a Bug could use one configuration and a Story another.

A field scheme replaces both. Atlassian's What are field schemes? page puts it like this: "Field schemes allow you to control which fields appear on your work items and how those fields behave across different spaces." Each space uses exactly one field scheme, and one scheme can serve many spaces, says the page on associating a space with a field scheme. If a field isn't in a space's scheme, it doesn't show up in that space.

Two older pieces keep their jobs, and it helps to keep them apart in your head. Field contexts now only set the content of a field, meaning default values and the options in a dropdown, and they no longer hide a field from a space. Atlassian's general availability post says each field now gets a global context that can't be deleted. Screens, screen schemes and layouts "remain the final gatekeepers for what users actually see", in the words of that same post.

So a field has to be in the space's field scheme and on the screen before anyone sees it, and its context decides what it's filled with.

Per-work-type differences moved inside the scheme. On a field's row you open More actions and pick Change field behavior by work type. A side panel then lets you set Available on and Required on per work type, and replace the field description for one work type, as described in Change the way fields behave for different work types. Below is one of our service-space schemes; look at the two columns on the right.

A field scheme page in Jira Cloud: Jira Service Management Field Configuration Scheme for Project JT, 1 space uses this scheme, 157 fields, with columns Name, Field type, Description, Available on and Required on, most rows reading All work types and No work types

A new custom field is not added to any field scheme by itself. Atlassian's Create or edit a field scheme page says you must add it to the relevant schemes before it appears in your spaces. If someone on your team creates a field and tells you "it's not showing", start there.

Where do you find it? In Jira, select Settings, then Work items, then Field schemes in the sidebar. When we opened the old admin addresses, /secure/admin/ViewFieldLayouts.jspa and /secure/admin/ViewFieldLayoutSchemes.jspa, they redirected straight to the Field schemes page, so old bookmarks won't show you the old screens any more.

When the field schemes migration reached your site

Atlassian announced general availability on 10 June 2026 in Announcing General Availability of Field Schemes. Continuous release track sites were converted over the following weeks. Bundled release track sites were expected in September, and Carol Low's comment above put them on 10 November. The Cloud roadmap lists "Field schemes - GA" as released, 2026 Q3, for Jira and Jira Service Management.

You didn't get to pick the hour. In a June comment on the FAQ, Atlassian staff wrote that the conversion "runs automatically, in the maintenance window of your site", and that moving the site to bundled release tracks was the one way to control the timing. In her 20 October comment, Carol Low added that a site still on the old screens was most likely on a bundled track.

What the field schemes migration created on our Jira Cloud site

The migration's logic is described in the original announcement, Say goodbye to field configuration schemes and hello to the future of Jira (49,198 views and 48 comments on 15 November). It reads your field configurations, which spaces use them, the fields in those spaces and the work types they apply to, and then your field contexts. Then it creates field schemes so that the fields people see today stay visible, with this warning: "you may have more schemes than you began with fewer spaces associated with each scheme."

It also tidies up. Fields that aren't used in the linked spaces lose their association. A field counts as used if it holds a value on a work item, sits on a screen, is required, is used in a workflow, or is used in a form. A field that used to be limited to some work types by its context gets the same limit inside the scheme, so it doesn't suddenly appear.

Here's our site afterwards. We read all 43 schemes through the new API and matched each one to its spaces.

The Jira Cloud Field schemes list: 43 field schemes, the Default Field Scheme marked Default on 49 spaces with 471 fields, several Showcase field schemes on 1 space each, and Jira Service Management schemes for spaces showing 0 spaces with 170 and 79 fields

What Count on our site
Field schemes in the new list 43
Field configuration schemes still in the old list 32
Live company-managed spaces 59
Field schemes linked to at least one space 19
Field schemes linked to no space 24
After we deleted one orphan (see the cleanup) 42 schemes, 23 with no space
Live spaces on the Default Field Scheme 42 (49 counting spaces in the trash)
Team-managed spaces 11, listed under no field scheme

The 24 orphans are all named "Jira Service Management Field Configuration Scheme for Space" plus a space key, and the spaces behind them are gone. On our site each service space had its own scheme, and deleting the space left the scheme behind. They hold between 69 and 233 fields each. They don't break anything, but they pad the list to 43 rows when 19 are in use.

A cartoon robot on a wooden stepladder holding a feather duster in front of a tall metal shelf stacked with dusty cobwebbed cardboard boxes whose top row is fading away as translucent dashed outlines, while only one short row of glowing yellow boxes is cabled to a small green machine, and a smaller robot shrugs at a separate dusty heap beside a box painted with a yellow star.

Spaces in the trash still count. The Default Field Scheme says 49 spaces, and 7 of those 49 are spaces we had deleted that are still in the trash. If you count your spaces from the project list and your schemes from this page, the numbers won't agree while those spaces sit in the trash.

Team-managed spaces don't appear under any scheme. Their fields are managed inside each space. A public bug, JRACLOUD-99816, shows they have a project-level field scheme behind the scenes, but it isn't one you'll see on this page.

Our numbers are small. We had 32 old schemes and ended up with 43, mostly because of our own test spaces. Your count depends on how you used field contexts. Carol Low wrote in September that if you mostly use global contexts, the migration "shouldn't result in individual schemes", but if you lean on space-specific contexts you can end up with many more. One admin wrote in June that they had 10 field configuration schemes in production. Once the change reached their sandbox, they counted 343 field schemes. So before you plan anything, open the page and read your own count.

The 700-field limit now counts per field scheme

Jira Cloud has enforced a limit of 700 fields per space since March 2026, according to Data limits and guardrails in Jira Cloud. That page still describes the fields as the ones "included in field configuration schemes associated with the space". Atlassian's release note on jirareleases.atlassian.com says "A limit of 700 fields applies per scheme". Carol Low wrote on 20 October that "Removing a field from a scheme reduces the count, and you don't have to trash it."

So if you're close to 700, you remove fields from the field scheme. Our default scheme has 471 fields, comfortably under. Removing a field from a scheme doesn't delete its data, says Atlassian's Optimize fields per space page, but its values aren't accessible until the field is added back.

The 150-work-type limit you may have seen quoted per scheme now sits on the space, through its work type scheme, according to the same guardrails page.

Which scripts break on the old Jira field configuration scheme API

Atlassian's REST reference marks all 15 old operations under /rest/api/3/fieldconfiguration and /rest/api/3/fieldconfigurationscheme as deprecated, with "use Field schemes" as the instruction. None of them has a removal date. The Migration Guide for API Users, written by Atlassian staff, covers writes. It says nothing about reads, and reads are where we found problems that don't show up as errors.

The old reads still answer, with different numbers

We asked both APIs about the same three spaces.

Bar chart from our test site, 15 November 2026: the old API lists 740, 165 and 170 field configuration items for the default, the JT service space and the TPP test space; their field schemes hold 471, 157 and 180 fields

For the default, the old API listed 740 items, none hidden, and the Default Field Scheme has 471 fields. 118 of those 740 are field ids that the site's own field list no longer returns. Of the old list's fields that still exist, 152 aren't in the new scheme, which fits the documented tidy-up of unused fields, so I don't read them as a bug. But a report built on the old endpoint now counts fields your users can't see. Required fields matched in all three pairs.

And the old list of schemes is incomplete. Twelve schemes made on 10 September by our own test-data script, through the new API, aren't in the old list at all. A script that inventories field configuration schemes the old way misses those 12.

And the old lookup of which scheme a space uses, GET /rest/api/3/fieldconfigurationscheme/project, returned {"total":0,"values":[]} for all 70 spaces. That's HTTP 200 with an empty list. We checked it wasn't our query: the same family's mapping call for scheme 10005 still returned its row. None of Atlassian's pages we read documents this behaviour of the old reads, so treat it as what we measured on one site.

"The field configuration was not found." on a write

Writes are documented. The migration guide's words are "Embrace the 404: Once a project migrates to the new architecture, legacy update APIs will return a 404 Not Found." On our site it came back on an id that the old API still reads without trouble:

Our API calls against our test site on 15 November 2026, re-typeset from our probe logs: GET on field configuration 10014 returns HTTP 200 with 170 items, PUT on the same id returns HTTP 404 The field configuration was not found, the old project lookup returns total 0, and PUT on the new field schemes parameters endpoint returns HTTP 200 success true

If a script logs that message, nobody deleted your configuration. Your site has moved to field schemes, and the script needs the new endpoint.

A cartoon robot courier holding a blank envelope scratches its head in front of an old round doorway boarded shut and covered in cobwebs, while a robot custodian shrugs beside it holding a broom and an empty dustpan, and a taller robot gestures warmly from a new open archway with a green carpet runner and a signpost showing an arrow.

The new endpoint, and one trap in the example payload

The replacement lives under /rest/api/3/config/fieldschemes, 15 operations in the Jira Cloud REST API spec. They need the Administer Jira permission. All 15 are still flagged experimental, and the group's description still says beta and opt-in, even though the feature is generally available.

To change a field's description in one scheme we called PUT /rest/api/3/config/fieldschemes/fields/parameters. Our first try copied the spec's example, which includes a rendererType. On the system field labels it failed with HTTP 400 and "Field labels cannot have renderer type changed", although we sent the value it already had. Sending only the description worked. This is the body we sent:

{"labels": [{"parameters": {"description": "lz-probe-20261115 new-api write"}, "schemeIds": [2]}]}
Enter fullscreen mode Exit fullscreen mode

The call returned HTTP 200 with "success": true, the description changed in scheme 2 only, and the default scheme kept its empty description. We put the old description back with the same call. Note that the endpoint reports results per field and per scheme, so a script should read success in the body as well as the status code.

What to tell app vendors and script owners

Atlassian's own line is that "scripts relying on legacy field configuration APIs will need to be updated", while automation rules keep working. I'd hand your script owners this list:

  1. Search your scripts for fieldconfiguration and fieldconfigurationscheme. A hit that only reads is the risky one, because it won't error.
  2. Change project lookups to GET /rest/api/3/config/fieldschemes/projects?projectId=.... Atlassian's spec calls this "a temporary API" for the transition, and like the rest of the new group it's flagged experimental, so keep an eye on it.
  3. Treat a 404 from an old write as "this site has moved" and switch the call over.
  4. Leave rendererType out of parameter updates unless you mean to change it.
  5. Ask each app vendor whether they've moved off the old field configuration API.

On vendors, I found one notice. Adaptavist's ScriptRunner for Jira Cloud scripted fields page says new custom fields are no longer linked to all schemes automatically, and that field configurations are merging into field schemes. I couldn't find a notice from Appfire or other vendors, so it's worth asking them directly.

If you're also creating spaces by script, Atlassian's RFC-121 says the field configuration settings in the create-project call will be deprecated too.

Field schemes cleanup: orphaned schemes, the shared default and sprawl

We ran this cleanup on our site in the order below, and you'll need to be a Jira admin for it. We deleted through the REST API with an API token. On Premium and Enterprise, the Site optimizer can also delete an unassociated scheme from the screen; we didn't test the page's own Actions menu for a delete option.

  1. In Settings > Work items > Field schemes, read the Spaces column. A row with 0 spaces is an orphan candidate; check its name and description first, because a scheme someone built and hasn't linked yet also shows 0. Ours had 24, all named after deleted service spaces.
  2. Remember the trash. A deleted space that's still in the trash keeps its scheme linked, so that scheme won't show 0 spaces while the space sits there.
  3. Find the orphan's id with GET /rest/api/3/config/fieldschemes (each entry has id, name and a link to its spaces), then delete it with DELETE /rest/api/3/config/fieldschemes/{id}. Ours returned HTTP 200 and {"id":"640","deleted":true}, and the list dropped from 43 to 42.
  4. Expect two refusals. A scheme a space uses returns HTTP 409 "Scheme is in use and cannot be deleted". The Default Field Scheme returns HTTP 400 "System schemes cannot be deleted".
  5. Open the Default Field Scheme and check its field count against 700. Most of your spaces probably share it, so a field you add there counts for each of them.
  6. Add any custom field created since the migration to the schemes that need it, because Jira won't do it for you.

When you're done, the Field schemes page shows no 0-space rows you can't explain, and the default scheme's field count is under 700.

When should you merge schemes? If two schemes hold the same fields and only differ by a few required fields, you can now express that inside one scheme with Required on. Atlassian's FAQ says a large number of schemes won't slow your site down, while too many fields in one scheme can. So I'd consolidate for the people maintaining it, and trim fields for the limit.

What I'd do this week

Open your Field schemes page and write down your total schemes, the schemes with 0 spaces, and the fields in the default. Then send the five-point list above to the people who maintain your scripts and apps, before a monthly report quietly goes wrong. Do the scripts first, and leave the cleanup for a calm afternoon.

There's one thing I couldn't confirm: which Jira plans field schemes apply to. None of the Atlassian pages I read states a plan, and the only plan-limited piece I found is the Site optimizer (Premium and Enterprise), so check your own site before you promise anything to your team. If you're moving from Data Center, Atlassian says the migration assistant converts field configurations when the target site already has field schemes, and our note on the Jira Cloud Migration Assistant export error for custom field config schemes covers one place that goes wrong. For the admin time all this takes, our piece on how many Jira administrators you need has the numbers, and the formula fields tutorial covers the limits of formula fields themselves.

If you've been through this on a bigger site, I'd love to hear your scheme count before and after, and whether any of your apps tripped over the old API.


Originally published on leanzero.net. More Atlassian, Forge and local-AI write-ups at leanzero.net/blog, and if you're planning a migration or a Forge app, that's what we do: leanzero.net/services.

Top comments (0)