Jira issue linking model

Introduction

This guide explains the Jira issue linking model to aid understanding of how issue links work and how to interpret issue link details exposed by the Jira REST APIs.

APIs

Issue link information is exposed in the REST API, such as in GET /rest/api/3/issueLink/{linkId} and GET /rest/api/3/issue/{issueIdOrKey}. These operations return link information like this:

1
2
{
  type: {
    name: string
    inward: string
    outward: string
    ... additional fields omitted for brevity ...
  },
  inwardIssue or outwardIssue: {
    key: string
    ... linked issue data ...
  }
}

Issue link types

Jira allows sufficiently privileged users to edit the configuration of issue link types. Each type of issue link comprises three pieces of information:

• Name of the issue link type
• Outward link description
• Inward link description

Here is a typical issue link configuration, which can be obtained by calling GET /rest/api/3/issueLinkType:

1
2
"issueLinkTypes": [{
  "id": "10000",
  "name": "Blocks",
  "inward": "is blocked by",
  "outward": "blocks",
  "self": "..."
}, {
  "id": "10007",
  "name": "Depends",
  "inward": "is depended on by",
  "outward": "depends on",
  "self": "..."
}]

Issue link directionality

Jira issue links are bidirectional, however, the semantics of each direction is only interpretable at the user interface level and not at the API level. The following diagram illustrates the creation of four links between issues THING-1 and FEAT-1, FEAT-2, FEAT-3, and FEAT-4. The Jira issue view uses the labels provided in the issue link type configuration to suggest the directionality of the links.

If the details of THING-1: Car are retrieved using the REST API using GET /rest/api/3/issue/THING-1, the issueLinks field contains this information (where some fields are omitted for brevity):

1
2
issueLinks: [{
  type: {
    name: "Blocks",
    inward: "is blocked by",
    outward: "blocks"
  },
  inwardIssue: {
    key: "FEAT-1"
  }
}, {
  type: {
    name: "Blocks",
    inward: "is blocked by",
    outward: "blocks"
  },
  inwardIssue: {
    key: "FEAT-3"
  }
}, {
  type: {
    name: "Depends",
    inward: "is dependend on by",
    outward: "depends on"
  },
  outwardIssue: {
    key: "FEAT-2"
  }
}, {
  type: {
    name: "Depends",
    inward: "is dependend on by",
    outward: "depends on"
  },
  outwardIssue: {
    key: "FEAT-4"
  }
}]

This diagram provides a model for interpreting the issue link data returned by the Jira API. The links are drawn with labeled ends rather than arrows implying direction.

The inwardIssue and outwardIssue fields identify the link end type and are used to determine the label to display in the user interface. For example, if the issue link data contains an inwardIssue field, the link should be labeled with the value of the type.inward field.