RFC-105: New Field Scheme Model APIs for Field Configuration Backup, Restoration, and Management

General Request for Comments (RFC)
, , ,
1

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 perform any read and write operations that support backup and restoration of configurations.

Proposed Solution

Field Scheme APIs

1. Get Field Schemes

GET /rest/api/3/fieldscheme
Returns field schemes for scheme id provided.

Query parameters:

  • startAt (integer)
  • maxResults (integer)
  • id (array)

Response:

{
  "isLast": true,
  "maxResults": 10,
  "startAt": 0,
  "total": 3,
  "values": [
    {
      "id": "10000",
      "name": "Field Scheme for Bugs",
      "description": "This field scheme is for bugs only."
    },
    {
      "id": "10001",
      "name": "Field Scheme for software related projects",
      "description": "We can use this one for software projects."
    },
    {
      "id": "10002",
      "name": "Field Scheme for Epics",
      "description": "Use this one for Epic work type."
    }
  ]
}

2. Create Field Scheme

POST /rest/api/3/fieldscheme
Creates field scheme with name and description provided via request body.

Request:

{
  "description": "My field configuration description",
  "name": "My Field Scheme"
}

Response:

{
  "description": "My field configuration description",
  "id":"10001",
  "name": "My Field Scheme"
}

3. Update Field Scheme

PUT /rest/api/3/fieldscheme/{id}
Updates existing field scheme with name and description provided via request body.

Path parameters:

  • id (integer)

Request:

{
  "description": "We can use this one for software projects.",
  "name": "Field Scheme for software related projects"
}

4. Delete Field Scheme

DELETE /rest/api/3/fieldscheme/{id}
Deletes existing field scheme for the scheme id provided.

Path parameters:

  • id (integer)

5. Get Field Scheme to Project Mapping

GET /rest/api/3/fieldscheme/project
Returns field scheme id to project ids mapping.

Query parameters:

  • startAt (integer)
  • maxResults (integer)
  • projectId (array)

Response:

{
  "isLast": true,
  "maxResults": 50,
  "startAt": 0,
  "total": 5,
  "values": [
    {
      "fieldScheme": {
        "id":"10002",
        "name": "Field Scheme for software related projects",
        "description": "We can use this one for software projects."
      },
      "projectIds": [
       "10000",
        "10001",
        "10002"
      ]
    }
  ]
}

6. Update Field Scheme for Project

PUT /rest/api/3/fieldscheme/project
Updates field scheme id for the project id provided.

Request:

{
  "fieldSchemeId": "10000",
  "projectId": "10000"
}

Field Scheme Item APIs

7. Get Field Scheme Items

GET /rest/api/3/fieldscheme/{id}/fields
Returns field’s configuration and mapping to work types, such as isRequired or description. The field id filter is optional.

Path parameters:

  • id (integer)

Query parameters:

  • startAt (integer)
  • maxResults (integer)
  • fieldId (array)

Response:

{
  "isLast": true,
  "maxResults": 50,
  "startAt": 0,
  "total": 5,
  "values": [
    {
      "fieldId": "customfield_10000",
      "parameters": {        
        "10010": {
          "isRequired": false,
          "description": "Special description for work type 10010"
        },
        "10011": {
          "renderer": "wiki-renderer"
        },
        "default": {
          "isRequired": true,
          "renderer": "text-renderer",
          "description": "Default description"
        }
      }
    },
    {
      "fieldId": "customfield_10001",
      "parameters": {
        "default": {
          "description": "Special description for issue type 10010",
          "isRequired": true,
          "renderer": "wiki-renderer"
        }
      }
    }
  ]
}

8. Update Field Associations

PUT /rest/api/3/fieldscheme/{id}/fields/association
Updates field’s association for given scheme id and work types. Supports ADD, REPLACE, and REMOVE operations.
*ADD operation adds given work type mapping on top of what is already configured for the field.
*workTypes are optional and if not provided, fields are added to default mapping. If one or more REMOVE are provided, fields are added to specific work type.
*REPLACE operation works as PUT and replaces existing mapping with what is provided in the request
*REMOVE operation removes provided work type mapping of the field

  • workTypes are optional and if not provided, fields are removed from default mapping. If one or more workTypes are provided, fields are removed from specific work type.
  • Removing a field from any work type removes existing parameters attached to it.

Path parameters:

  • id (integer)

Request Example:

{
  "values": {
    "customfield_10000": {
      "type": "ADD"
    },
    "customfield_10001": {
      "type": "ADD",
      "workTypes": [
        "10010", "10011"
      ]
    },
    "customfield_10001": {
      "type": "REPLACE",
      "workTypes": [
        "10010", "10011"
      ]
    },
    "customfield_10021": {
      "type": "REMOVE"
    }
  }
}

Request Example 2:

{
  "values": {
    "customfield_10001": {
      "type": "ADD",
      "workTypes": [
        "10010", "10011"
      ]
    },
    "customfield_10001": {
      "type": "REPLACE",
      "workTypes": [
        "10010", "10011"
      ]
    },
    "customfield_10021": {
      "type": "REMOVE",
      "workTypes": [
        "10011"
      ]
    }
  }
}

9. Update Field Parameters

PUT /rest/api/3/fieldscheme/{id}/fields/parameters
Updates field’s parameter mapping for given scheme id and work types. This is a PUT operation which replaces what’s inside mapping.

Path parameters:

  • id (integer)

Request:

{
  "values": [
    {
      "field_id": "customfield_10000",
      "workTypes": {
        "10011": {
          "description": "Special description",
          "remove": [
            "isRequired"
          ]
        }
      }
    },
    {
      "field_id": "customfield_10002",
      "workTypes": {
        "10012": {
          "description": "Special description"
        }
      }
    },
    {
      "field_id": "customfield_10001",
      "workTypes": {
        "10012": {
          "description": "Special description"
        },
        "default": {
          "description": "Special description for work type 10010",
          "isRequired": false
        }
      }
    }
  ]
}

Use Cases & Examples

Field Association Use Cases

PUT /rest/api/3/fieldscheme/{id}/fields/association

Use Case
Associate fields to all or specific work types For scheme 10001, associate customfield_10000 to all work types and customfield_10001 to work types 10010 and 10011.

Request:

{
  "values": {
    "customfield_10000": { "type": "ADD" },
    "customfield_10001": { "type": "ADD", "work_types": ["10010", "10011"] }
  }
}
Use Case
Add association to new work types, keep existing For scheme 10001, associate customfield_10001 to new work type 10012 and keep existing.

Request:

{
  "values": {
    "customfield_10001": { "type": "ADD", "work_types": ["10012"] }
  }
}
Use Case
Replace association with new work types For scheme 10001, associate customfield_10001 only to work type 10012 (removes others).

Request:

{
  "values": {
    "customfield_10001": { "type": "REPLACE", "work_types": ["10012"] }
  }
}
Use Case
Remove association from specific work types For scheme 10001, unassociate customfield_10001 from work type 10012.

Request:

{
  "values": {
    "customfield_10001": { "type": "REMOVE", "work_types": ["10012"] }
  }
}
Use Case
Remove association from scheme completely For scheme 10001, unassociate customfield_10001 from the scheme.

Request:

{
  "values": {
    "customfield_10001": { "type": "REMOVE" }
  }
}

Field Parameters Use Cases

PUT /rest/api/3/fieldscheme/{id}/fields/parameters

Use Case
Update description and make required for a work type For scheme 10001, update customfield_10000 to set description and make required for work type 10011.

Request:

{
  "values": [
    {
      "fieldId": "customfield_10000",
      "workTypes": {
        "10011": {
          "description": "Special description",
          "isRequired": true
        }
      }
    }
  ]
}
Use Case
Update description and remove required configuration For scheme 10001, update description and remove required for customfield_10000 on work type 10011.

Request:

{
  "values": [
    {
      "fieldId": "customfield_10000",
      "workTypes": {
        "10011": {
          "description": "Updated description",
          "remove": ["isRequired"]
        }
      }
    }
  ]
}
Use Case
Update multiple work type configurations For scheme 10001, update customfield_10001: 1. Set description for work type 10012 2. Make optional and set description for default mapping

Request:

{
  "values": [
    {
      "fieldId": "customfield_10001",
      "workTypes": {
        "10012": { "description": "Special description" },
        "default": { "description": "Special description for work type 10010", "is_required": false }
      }
    }
  ]
}

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 allows users to fetch or update field configuration, field configuration scheme, items and mappings.