RFC-104: New Field Scheme Model APIs for Project and Work Type Associations

General Request for Comments (RFC)
, , ,
1

Updated 19th September 2025 to include changes to proposed payloads incorporating feedback and aligning with Jira’s upcoming terminology refresh.

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 read field configuration information, their alignment with field configuration schemes, and mappings. These will replace the old APIs when they’re deprecated in the future.

Proposed Solution

To replace these APIs, below is the new API that returns a field’s context project and work type association settings.

This proposed API will support projects that are using the new field schemes as well as projects on the existing field configuration model, meaning it can be used as customers transition to the new model.

Get Field Association Items

GET /rest/api/3/projects/fields
Returns fields with parameters for given projects and work types.

Query parameters:

  • startAt (integer)

  • maxResults (integer, max: 100)

  • projectIds (array, required)

  • workTypeIds (array, required)

  • fieldIds (array)

Response:

{
  "isLast": true,
  "maxResults": 50,
  "nextPage": "/rest/api/2/projects/fields?projectId=10000&workTypeId=10001,10002&fieldId=environment&startAt=5"
  "startAt": 0,
  "total": 3,
  "values": [
    {
      "fieldId": "environment",
      "projectId": "10000",
      "workTypeId": "10001",
      "description": "For example operating system, software platform and/or hardware specifications (include as appropriate for the work).",
      "isRequired": false
    },
    {
      "fieldId": "environment",
      "projectId": "10000",
      "workTypeId": "10002",
      "description": "For example operating system, software platform and/or hardware specifications (include as appropriate for the work).",
      "isRequired": false
    }
  ]

Use Cases

Use Case 1:

User wants to know which fields are required for project, 10000, and work type, 10001.

Request

`/rest/api/3/projects/fields?projectIds=10000&workTypeIds=10001

Use Case 2:

User wants to know which fields customfield_10000 and customfield_10001 is required for project, 10000, and work type, 10001.

Request
/rest/api/3/projects/fields?projectIds=10000&workTypeIds=10001&fieldIds=customfield_10000,customfield_10001

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 providing field configuration, field configuration scheme, items and mappings to eventually fetch which fields are configured to the given project and work type context.

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

Hello @LeanneWon - thank you for the RFC. Can you already disclose which permissions the new API endpoints will require?
I was wondering whether to use these ones vs createmeta for certain operations

1 Like
3

Hi @ernst.stefan
Yes, I will update the document with more information about permissions. To give you the answer quickly, this API will not require admin permission to make request.

4

Hello

Will you add it to the REST API is version 3 as well?

5

Hi @OndejMedek, Yes, I will be available for both version 2 and 3

6

@LeanneWon, in most other API endpoints it’s called issuetype, but here it’s called workType. That is in-consistent. Is that intentional?

7

Hi @AndreasEbert

As part of the change this year, issue type is now renamed to be work type. For an official announcement, you may refer to:

https://community.developer.atlassian.com/t/work-is-the-new-collective-term-for-items-tracked-in-jira/88552

To align with this change, we are intentionally making new APIs to be aligned with the new term, “work type”. However for the existing APIs, we are keeping them as issue type to ensures that no backward-incompatible changes are introduced.

Thanks!

1 Like
8

Hi,

My question is about contexts:
In your proposed solutions example, which returns the same field associated to the project with different work types => Are there still underlying context with a contextId? If yes how should we retrieve the contextId once we have this response?

[
    {
      "fieldId": "environment",
      "projectId": "10000",   ====> CONTEXT ID
      "workTypeId": "10001",  ====> 123 ??? 
      "description": "For example operating system, software platform and/or hardware specifications (include as appropriate for the work).",
      "isRequired": false
    },
    {
      "fieldId": "environment",
      "projectId": "10000",   ====> CONTEXT ID
      "workTypeId": "10002",  ====> 456 ??? 
      "description": "For example operating system, software platform and/or hardware specifications (include as appropriate for the work).",
      "isRequired": false
    }
  ]

Cheers,

Bernhard

9

Hi @clouless

Sorry for the delayed response.

In your proposed solutions example, which returns the same field associated to the project with different work types => Are there still underlying context with a contextId?

With new model, there is no guarantee that there is context for the field returned from this API as the goal of new Field Scheme model is to have fields will be directly associated with Field scheme. This means users can no longer restrict a field to a project by deleting its global context and replacing it with a project-limited one. This can result in having fields returned from this proposed API and does not have applicable context for the given project and work types. (As started in RFC-103: Jira Field Configuration Overhaul: Admin Experience and API Changes)

Once everyone is onboarded to use new Field Schemes, we are going to make sure there is always global context exist for all the fields, but this won’t happen until the old Field Config Schemes are fully deprecated.

Thanks!

Leanne

1 Like
10

Seem to me, for the Use Case 1: User wants to know which fields are required for project, 10000, and work type, 10001 - it’s possible to use endpoint Get create field metadata for a project and issue type id too. Is this endpoint going to be deprecated, too?

11

Hi @OndejMedek

Yes you can keep using Get create field metadata for a project and issue type id endpoint and it is not being deprecated as part of this RFC.

Thanks,

Leanne

12

Hi @LeanneWon If Get create field metadata for a project and issue type id endpoint and my be others (e.g. Get edit issue metadata ? ) will be deprecated by this RFC, may you add them to the Affected APIs section in your intro post?

13

Hi @OndejMedek

Apologies, there was typo when I posted the last reply, it was supposed to be

it is not being deprecated as part of this RFC.

Those APIs will not be deprecated by this RFC and you can continue to use them.

2 Likes