From Field Configurations to Field Schemes: Migration Guide for API Users

[#1]

👋 Hey there! I’m Leanne, a Senior Engineer on the Jira team.

We know that managing field configurations can sometimes feel like a game of 3D chess, so we’re making things a lot simpler.From June 2026, we will begin the progressive rollout of Field Schemes, the unified method to manage custom fields. For more information about changes involved in the rollout.

As we move away from Field Configurations and Field Configuration Schemes, the existing public REST APIs will be deprecated. New REST APIs will allow interaction with Field Schemes. The old model uses a two-tier approach: you create Field Configurations (containers for field settings), then Field Configuration Schemes that map work types to those configurations. The new model uses a single-tier Field Scheme that directly holds field associations, per-field parameters, and project assignments.

API Documentation Links

• Old APIs: Issue Field Configurations API Group

• New APIs: Field Schemes API Group

Key Migration Tips

Important behavioral differences to watch for:

1. No more two-tier management: You no longer need to create a field configuration first, then wire it to a scheme. Fields, their parameters, and project assignments are all managed directly on the Field Scheme.

2. isHidden is replaced by association: Instead of marking a field as "hidden," simply don't associate it with the scheme (or remove it using DELETE /rest/api/3/config/fieldschemes/fields).

3. Work type mapping → Work type parameters: Instead of creating separate field configurations per work type, use work-type-specific parameter overrides on individual fields.

4. Bulk operations: The new API favors efficiency—you can update field parameters, field associations, and project associations across multiple schemes in a single request.

Concept	Old Model	New Model
Container for field settings	Field Configuration — a named group of field items (isHidden, isRequired, description, renderer)	Field Scheme — a named scheme that directly associates fields with per-field parameters
Work type mapping	Field Configuration Scheme — maps work types → field configurations Two-tier: create a field config, then create a scheme that maps work types to configs	Work Type Parameters — per-field overrides keyed by work type (work type), defined inline on the scheme Single-tier: one scheme holds fields, their parameters, work-type overrides, and project associations
Field settings	FieldConfigurationItem: isHidden, isRequired, description, renderer	Field Parameters: isRequired, description (with optional work-type-level overrides)

1️⃣ Scheme / Configuration anagement

Conceptual changes to merge Field Configurations and Field Configuration Schemes into a single Field Schemes entity, reducing two-tiered configuration to a single tier where Field Schemes holds all field-related configurations and associations.

Legacy use case / API	New API migration path
List existing field configurations GET /fieldconfiguration	No direct equivalent for field configuration. GET /config/fieldschemes
List field configuration schemes GET /fieldconfigurationscheme
Create a field configuration POST /fieldconfiguration	No direct equivalent for field configuration. POST /config/fieldschemes
Create a field configuration scheme POST /fieldconfigurationscheme
Delete a field configuration DELETE /fieldconfiguration/{id}	No direct equivalent for field configuration.No direct equivalent for field configuration. DELETE /config/fieldschemes/{id}
Delete a field configuration scheme DELETE /fieldconfigurationscheme/{id}
Rename or update a field configuration PUT /fieldconfiguration/{id}	No direct equivalent for field configuration. PUT /config/fieldschemes/{id}
Rename or update a field configuration scheme PUT /fieldconfigurationscheme/{id}

¹ Delete the migrated scheme, or remove its field associations and parameters.

2️⃣ Field Management Use Cases

Here are use cases and how to achieve them today using legacy Field Configurations and Field Configuration Schemes APIs, and how to perform the same actions using the new Field Schemes API

Use cases with Legacy API	New API migration path
Read all fields and configurations for a space
Find scheme by space ID GET /fieldconfigurationscheme/project?projectId={projectId} Make multiple calls to to read all field configuration IDs within the scheme GET /fieldconfigurationscheme/mapping Read all fields and configurations from each field configuration GET /fieldconfiguration/{id}/fields	Find scheme by space ID GET /config/fieldschemes/projects Read all fields from the field scheme GET /config/fieldschemes/{id}/fields
Read all fields and configurations for a space and a work type
Find scheme by space ID GET /fieldconfigurationscheme/project?projectId={projectId} Read field configuration ID by work type GET /fieldconfigurationscheme/mapping Read all fields and configurations in a field configuration GET /fieldconfiguration/{id}/fields	Find scheme by space ID GET /config/fieldschemes/projects Read all fields from the field scheme GET /config/fieldschemes/{id}/fields Identify field IDs from responses linked by default and the work type you want
Check if certain field is required for a space and a work type
Find scheme by space ID GET /fieldconfigurationscheme/project?projectId={projectId} Read field configuration ID by work type GET /fieldconfigurationscheme/mapping Read all fields and configurations in a field configuration GET /fieldconfiguration/{id}/fields Look up field’s required configuration from the response	Find scheme by space ID GET /config/fieldschemes/projects Read field’s parameter from the field scheme by field ID GET /config/fieldschemes/{id}/fields/{fieldId}/parameters
Add fields to a space and all work types
Find scheme by space ID GET /fieldconfigurationscheme/project?projectId={projectId} Read all field configuration ID GET /fieldconfigurationscheme/mapping Make multiple calls to update all fields in all field configurations PUT /fieldconfiguration/{id}/fields	Find scheme by space ID GET /config/fieldschemes/projects Add field to the scheme PUT /config/fieldschemes/fields
Add fields to a space and specific work types
Find scheme by space ID GET /fieldconfigurationscheme/project?projectId={projectId} Read field configuration ID by work type GET /fieldconfigurationscheme/mapping If field configuration does not exist for work types Create a new field configuration POST /fieldconfiguration Map to the work type PUT /fieldconfigurationscheme/{id}/mapping Make multiple calls to update all fields in all field configurations PUT /fieldconfiguration/{id}/fields	Find scheme by space ID GET /config/fieldschemes/projects Add field to the scheme with specific work types PUT /config/fieldschemes/fields
Make fields required for multiple work types in a space
Find scheme by space ID GET /fieldconfigurationscheme/project?projectId={projectId} Read field configuration ID by work type GET /fieldconfigurationscheme/mapping If field configuration does not exist for work types Create a new field configuration POST /fieldconfiguration Map to the work type PUT /fieldconfigurationscheme/{id}/mapping Make multiple calls to update all fields in all field configurations PUT /fieldconfiguration/{id}/fields	Find scheme by space ID GET /config/fieldschemes/projects Update field’s parameter from the field scheme by field ID PUT /config/fieldschemes/fields/parameters
Remove fields from work types for a project
Find scheme by space ID GET /fieldconfigurationscheme/project?projectId={projectId} Read field configuration ID by work type GET /fieldconfigurationscheme/mapping If field configuration does not exist for work types Create a new field configuration POST /fieldconfiguration Map to the work type PUT /fieldconfigurationscheme/{id}/mapping Make multiple calls to make all fields hidden in all field configurations PUT /fieldconfiguration/{id}/fields with isHidden: true	Find scheme by space ID GET /config/fieldschemes/projects Update the field's restricted work type in the scheme to remove from certain work types PUT /config/fieldschemes/fields/parameters with restrictedToWorkTypes
Remove fields from a space completely
Find scheme by space ID GET /fieldconfigurationscheme/project?projectId={projectId} Read all field configuration ID GET /fieldconfigurationscheme/mapping Make multiple calls to make all fields hidden in all field configurations PUT /fieldconfiguration/{id}/fields with isHidden: true	Find scheme by space ID GET /config/fieldschemes/projects Remove field from the scheme DELETE /config/fieldschemes/fields

How to Prepare

We want this transition to be as smooth as possible. Here’s how you can stay ahead of the curve:

• Audit your scripts: Review any custom integrations or automations using the legacy Field Configuration APIs.

• Update to the new model: Start transitioning your logic to the Field Schemes API. This will give you access to bulk operations and a much simpler data model.

• Embrace the 404: Once a project migrates to the new architecture, legacy update APIs will return a 404 Not Found. This is a signal that the project has successfully moved to the streamlined Field Scheme model!

• Test in a Sandbox: We highly recommend spinning up a sandbox and joining the Open Beta to test your updated scripts in a safe environment.

Sign up now

Thanks for coming on this journey with us! If there’s anything we can clarify, please leave a comment or question below.