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

General Request for Comments (RFC)
, , ,
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.

1 Like