references

Last updated: Feb 20, 2026

DEVELOPER

IMPLEMENTATION

HEALTH TECH VENDOR

Definition

In a config modifier schema, use references to store a named value from a property or object that can be accessed later. This is beneficial in two use cases:

You need to use the same property multiple times throughout the schema.
You need to parse a different path before comparing or evaluating against the original property or value.

To access the stored value, you must include the use keyword as a sub-keyword to references. Learn about the use keyword.

Best practice

Use references sparingly. Parse values directly in place unless you specifically encounter one of the listed use cases. Overusing references can make the schema less readable and harder to maintain.

Order of execution

This keyword executes in the following order:

omit
constant
references
use
get
Mutually exclusive keywords at this level:
- properties
- if
- concat
- switch
- pipe
- merge
- prefer
- items
default
plugin

Example 1: Same property, multiple times

This example demonstrates the first use case for references: You need to use the same property multiple times throughout the schema.

For example, you can map PATIENT[0].PID.18.1 to the resource ID for FHIR® Appointment.

First, we check that identifier.value exists before setting its value.

Example 1: References input from initial payload

json

1
{
2
  "Meta": {
3
    "DataModel": "FHIR.Event.Scheduling",
4
    "Destinations": [
5
      {
6
        "ID": "3156f0f2-d249-4970-b50f-afffc8021d71",
7
        "Name": "ICE_UAT_LISTENER"
8
      }
9
    ],
10
    "EventDateTime": null,
11
    "EventType": "scheduling-appointment-updated",
12
    "FacilityCode": null,
13
    "Logs": [
14
      {
15
        "AttemptID": "01986857-f4ef-728a-a296-7b3e71daeac7",
16
        "ID": "01986857-f4ef-7a0f-9ab4-d5fca3c7b6a7"
17
      }
18
    ],
19
    "Message": {
20
      "ID": 74085725083
21
    },
22
    "Source": {
23
      "ID": "cc98b497-28ec-4182-94e5-21315c4eb359",
24
      "Name": "Northwestern (Hippocratic AI) FHIR.Event.Scheduling (SIU) Source (s)"
25
    },
26
    "Test": true,
27
    "Transmission": {
28
      "ID": 73168642269
29
    }
30
  },
31
  "entry": [
32
	 ...
33
    {
34
      "fullUrl": "urn:uuid:7f1989e4-b009-4ff1-85fe-c526932970fd",
35
      "resource": {
36
        "comment": "pls call the patient",
37
        "end": "2025-07-31T15:00:00.000Z",
38
        "identifier": [
39
          {
40
            "type": {
41
              "coding": [
42
                {
43
                  "code": "FILL",
44
                  "display": "Filler Identifier",
45
                  "system": "<http://terminology.hl7.org/CodeSystem/v2-0203>"
46
                }
47
              ],
48
              "text": "Filler Identifier"
49
            },
50
            "value": "200212133596"
51
          }
52
        ],
53
        "participant": [
54
          {
55
            "actor": {
56
              "reference": "urn:uuid:f06c8769-6f61-449c-963e-9ad26f786c94",
57
              "type": "Practitioner"
58
            },
59
            "status": "accepted",
60
            "type": [
61
              {
62
                "text": "MD"
63
              }
64
            ]
65
          },
66
          {
67
            "actor": {
68
              "reference": "urn:uuid:220d2650-d662-4de7-a437-744a32b4448d",
69
              "type": "Patient"
70
            },
71
            "status": "accepted"
72
          }
73
        ],
74
        "reasonCode": [
75
          {
76
            "text": "GI COLONOSCOPY SCREENING OPEN ACCESS"
77
          }
78
        ],
79
        "resourceType": "Appointment",
80
        "serviceType": [
81
          {
82
            "coding": [
83
              {
84
                "code": "1400",
85
                "display": "COLONOSCOPY, SCREENING",
86
                "system": "urn:redox:cc98b497-28ec-4182-94e5-21315c4eb359:NMGEAP"
87
              }
88
            ],
89
            "text": "COLONOSCOPY, SCREENING"
90
          }
91
        ],
92
        "start": "2025-07-31T14:30:00.000Z",
93
        "status": "proposed"
94
      }
95
    }
96
  ],
97
  "id": "6e8bbd16-c210-467e-a07c-5ef3cbdbf9dd",
98
  "resourceType": "Bundle",
99
  "timestamp": "2025-08-02T01:14:11.635Z",
100
  "type": "message"
101
}

Example 1: References selector

json

1
$.entry[?(@.resource.resourceType=="Appointment")].resource.identifier

Example 1: Config modifier with references keyword

yaml

1
references:
2
  csnValue:
3
    use: initialPayload
4
    get: PATIENT[0].PID.18.1
5
if:
6
  operator: all
7
  terms:
8
    - use: csnValue
9
  then:
10
    concat:
11
      - {}
12
      - properties:
13
          value:
14
            use: csnValue
15
          type:
16
            constant:
17
              coding:
18
                - code: CSN
19
                  display: Contact Serial Number
20
                  system: Northwestern Medical HL7v2 Definition
21
              text: Contact Serial Number (CSN)
22
  else:
23
    comment: return original value

During processing, the request checks if PID.18.1 exists in the initial payload. If so, the then action executes, meaning that PID.18.1 is set to the contact serial number (CSN). If PID.18.1 doesn’t exist, the else action executes, meaning that the original value is returned.

Example 1: References output

json

1
{
2
  "Meta": {
3
    "DataModel": "FHIR.Event.Scheduling",
4
    "Destinations": [
5
      {
6
        "ID": "3156f0f2-d249-4970-b50f-afffc8021d71",
7
        "Name": "ICE_UAT_LISTENER"
8
      }
9
    ],
10
    "EventDateTime": null,
11
    "EventType": "scheduling-appointment-updated",
12
    "FacilityCode": null,
13
    "Logs": [
14
      {
15
        "AttemptID": "01986857-f4ef-728a-a296-7b3e71daeac7",
16
        "ID": "01986857-f4ef-7a0f-9ab4-d5fca3c7b6a7"
17
      }
18
    ],
19
    "Message": {
20
      "ID": 74085725083
21
    },
22
    "Source": {
23
      "ID": "cc98b497-28ec-4182-94e5-21315c4eb359",
24
      "Name": "Northwestern (Hippocratic AI) FHIR.Event.Scheduling (SIU) Source (s)"
25
    },
26
    "Test": true,
27
    "Transmission": {
28
      "ID": 73168642269
29
    }
30
  },
31
  "entry": [
32
	 ...,
33
    {
34
      "fullUrl": "urn:uuid:7f1989e4-b009-4ff1-85fe-c526932970fd",
35
      "resource": {
36
        "comment": "pls call the patient",
37
        "end": "2025-07-31T15:00:00.000Z",
38
        "identifier": [
39
          {
40
            "type": {
41
              "coding": [
42
                {
43
                  "code": "FILL",
44
                  "display": "Filler Identifier",
45
                  "system": "<http://terminology.hl7.org/CodeSystem/v2-0203>"
46
                }
47
              ],
48
              "text": "Filler Identifier"
49
            },
50
            "value": "200212133596"
51
          },
52
          {
53
            "type": {
54
              "coding": [
55
                {
56
                  "code": "CSN",
57
                  "display": "Contact Serial Number",
58
                  "system": "Northwestern Medical HL7v2 Definition"
59
                }
60
              ],
61
              "text": "Contact Serial Number (CSN)"
62
            },
63
            "value": "200212139694"
64
          }         
65
        ],
66
        "participant": [
67
          {
68
            "actor": {
69
              "reference": "urn:uuid:f06c8769-6f61-449c-963e-9ad26f786c94",
70
              "type": "Practitioner"
71
            },
72
            "status": "accepted",
73
            "type": [
74
              {
75
                "text": "MD"
76
              }
77
            ]
78
          },
79
          {
80
            "actor": {
81
              "reference": "urn:uuid:220d2650-d662-4de7-a437-744a32b4448d",
82
              "type": "Patient"
83
            },
84
            "status": "accepted"
85
          }
86
        ],
87
        "reasonCode": [
88
          {
89
            "text": "GI COLONOSCOPY SCREENING OPEN ACCESS"
90
          }
91
        ],
92
        "resourceType": "Appointment",
93
        "serviceType": [
94
          {
95
            "coding": [
96
              {
97
                "code": "1400",
98
                "display": "COLONOSCOPY, SCREENING",
99
                "system": "urn:redox:cc98b497-28ec-4182-94e5-21315c4eb359:NMGEAP"
100
              }
101
            ],
102
            "text": "COLONOSCOPY, SCREENING"
103
          }
104
        ],
105
        "start": "2025-07-31T14:30:00.000Z",
106
        "status": "proposed"
107
      }
108
    }
109
  ],
110
  "id": "6e8bbd16-c210-467e-a07c-5ef3cbdbf9dd",
111
  "resourceType": "Bundle",
112
  "timestamp": "2025-08-02T01:14:11.635Z",
113
  "type": "message"
114
}

Example 2: Parse a different path before comparing

This example demonstrates the first use case for references: You need to parse a different path before comparing or evaluating against the original property or value. For this use case, a references keyword is commonly used when looping through arrays to track the current index being processed.

For example, you can convert every OBX.1 (set ID) from a number into a string. Since OBX.1 represents the Set ID, you can use this value to identify which specific observation to modify. You need references to:

Get the current OBX index (stored as currentObxId) from this loop.
Use that index to match against the correct observation record.

Limitation

The schema wouldn’t be valid for matching a value if references and currentObxId went directly under the match keyword.

This separation is exactly why references exist: To capture values from one parsing context so they can be used in another context where direct access isn’t possible.

Example 2: References input from initial payload

json

1
{
2
  "MSH": {
3
    "1": "|",
4
    "10": 74087159085,
5
    "12": {
6
      "1": "2.3"
7
    },
8
    "2": "^~\\&",
9
    "3": {
10
      "1": "REDOX"
11
    },
12
    "4": {
13
      "1": "RDX"
14
    },
15
    "6": {
16
      "1": "ZA300"
17
    },
18
    "7": {
19
      "1": "20250801183107"
20
    },
21
    "9": {
22
      "1": "ORU",
23
      "2": "R01"
24
    }
25
  },
26
  "PATIENT_RESULT": [
27
    {
28
      "ORDER_OBSERVATION": [
29
        {
30
          "NTE": [
31
          ],
32
          "OBR": {
33
            "1": 1,
34
            "13": null,
35
            "15": {
36
              "1": {
37
                "1": null
38
              },
39
              "4": {
40
                "1": null
41
              }
42
            },
43
            "16": [
44
              {
45
                "1": "1002198",
46
                "2": {
47
                  "1": "Alexander"
48
                },
49
                "3": "Mark",
50
                "7": null,
51
                "9": {
52
                  "1": null
53
                }
54
              }
55
            ],
56
            "2": {
57
              "1": "5000199677"
58
            },
59
            "22": {
60
              "1": "20250714150157"
61
            },
62
            "25": "P",
63
            "27": [
64
              {
65
                "6": null
66
              }
67
            ],
68
            "28": [
69
            ],
70
            "3": {
71
              "1": "5579782"
72
            },
73
            "4": {
74
              "1": "J774a",
75
              "2": "GenomeSeqDx (Trio)",
76
              "3": null
77
            },
78
            "7": {
79
              "1": "20250714160000"
80
            }
81
          },
82
          "OBSERVATION": [
83
            {
84
              "NTE": [
85
                ...
86
              ],
87
              "OBX": {
88
                "1": 1,
89
                "11": "P",
90
				...
91
            },
92
            {
93
              "NTE": [
94
              ],
95
              "OBX": {
96
                "1": 2,
97
                "11": "P",
98
                ...
99

100
              }
101
            },
102
            {
103
              "NTE": [
104
              ],
105
              "OBX": {
106
                "1": 3,
107
                "11": "P",
108
                ...
109
              }
110
            },
111
            {
112
              "NTE": [
113
              ],
114
              "OBX": {
115
                "1": 4,
116
                "11": "P",
117
                ...
118
              }
119
            },
120
            ...
121
            }
122
          ],
123
          "ORC": {
124
            "1": "RE",
125
            ...
126
          }
127
        }
128
      ],
129
      "PATIENT": {
130
        ...
131
      }
132
    }
133
  ]
134
}

Example 2: References selector

json

1
$.PATIENT_RESULT[0].ORDER_OBSERVATION[*].OBSERVATION[*].OBX

Example 2: Config modifier with references keyword

yaml

1
references:
2
  OBX: {}
3
  currentObxId:
4
    pipe:
5
      - use: '@parent'
6
        get: OBX.1
7
      - plugin:
8
          name: convert
9
          action: number-to-string
10
merge:
11
  - use: OBX
12
  - properties:
13
      '1':
14
        pipe:
15
          - use: initialPayload
16
            get: PATIENT_RESULT
17
            items:
18
              pipe:
19
                - get: ORDER_OBSERVATION
20
                  items:
21
                    pipe:
22
                      - get: OBSERVATION
23
                        plugin:
24
                          name: array
25
                          action: find
26
                          parametersIsProperty: true
27
                          parameters:
28
                            properties:
29
                              match:
30
                                properties:
31
                                  OBX.1:
32
                                    use: currentObxId
33
                      - get: OBX.1
34
                - plugin:
35
                    name: array
36
                    action: flatten
37
          - plugin:
38
              name: array
39
              action: flatten
40
          - get: '0'

During processing, OBX.1 is converted from a number to a string, so the value is now wrapped in quotes.

Example 2: References output

json

1
{
2
  "MSH": {
3
    "1": "|",
4
    "10": 74087159085,
5
    "12": {
6
      "1": "2.3"
7
    },
8
    "2": "^~\\&",
9
    "3": {
10
      "1": "REDOX"
11
    },
12
    "4": {
13
      "1": "RDX"
14
    },
15
    "6": {
16
      "1": "ZA300"
17
    },
18
    "7": {
19
      "1": "20250801183107"
20
    },
21
    "9": {
22
      "1": "ORU",
23
      "2": "R01"
24
    }
25
  },
26
  "PATIENT_RESULT": [
27
    {
28
      "ORDER_OBSERVATION": [
29
        {
30
          "NTE": [
31
          ],
32
          "OBR": {
33
            "1": 1,
34
            "13": null,
35
            "15": {
36
              "1": {
37
                "1": null
38
              },
39
              "4": {
40
                "1": null
41
              }
42
            },
43
            "16": [
44
              {
45
                "1": "1002198",
46
                "2": {
47
                  "1": "Alexander"
48
                },
49
                "3": "Mark",
50
                "7": null,
51
                "9": {
52
                  "1": null
53
                }
54
              }
55
            ],
56
            "2": {
57
              "1": "5000199677"
58
            },
59
            "22": {
60
              "1": "20250714150157"
61
            },
62
            "25": "P",
63
            "27": [
64
              {
65
                "6": null
66
              }
67
            ],
68
            "28": [
69
            ],
70
            "3": {
71
              "1": "5579782"
72
            },
73
            "4": {
74
              "1": "J774a",
75
              "2": "GenomeSeqDx (Trio)",
76
              "3": null
77
            },
78
            "7": {
79
              "1": "20250714160000"
80
            }
81
          },
82
          "OBSERVATION": [
83
            {
84
              "NTE": [
85
                ...
86
              ],
87
              "OBX": {
88
                "1": "1",
89
                "11": "P",
90
				...
91
            },
92
            {
93
              "NTE": [
94
              ],
95
              "OBX": {
96
                "1": "2",
97
                "11": "P",
98
                ...
99

100
              }
101
            },
102
            {
103
              "NTE": [
104
              ],
105
              "OBX": {
106
                "1": "3",
107
                "11": "P",
108
                ...
109
              }
110
            },
111
            {
112
              "NTE": [
113
              ],
114
              "OBX": {
115
                "1": "4",
116
                "11": "P",
117
                ...
118
              }
119
            },
120
            ...
121
            }
122
          ],
123
          "ORC": {
124
            "1": "RE",
125
            ...
126
          }
127
        }
128
      ],
129
      "PATIENT": {
130
        ...
131
      }
132
    }
133
  ]
134
}

Example 3: Parent variable

Redox has a predefined @parent variable that can be used to get the parent object or array of a property. See a references example with @parent.

FHIR® is a registered trademark of Health Level Seven International (HL7) and is used with the permission of HL7. Use of this trademark does not constitute an endorsement of products/services by HL7®.