# references

## 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: 

1. You need to use the same property multiple times throughout the schema.
2. 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](/how-to-use-redox/change-data-with-config-modifiers/build-a-config-modifier-schema/use).

> **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: 

1. `omit`
2. `constant`
3. **`references`**
4. `use`
5. `get`
6. Mutually exclusive keywords at this level:
   - `properties` 
   - `if` 
   - `concat` 
   - `switch` 
   - `pipe` 
   - `merge` 
   - `prefer` 
   - `items`
7. `default`
8. `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
{
  "Meta": {
    "DataModel": "FHIR.Event.Scheduling",
    "Destinations": [
      {
        "ID": "3156f0f2-d249-4970-b50f-afffc8021d71",
        "Name": "ICE_UAT_LISTENER"
      }
    ],
    "EventDateTime": null,
    "EventType": "scheduling-appointment-updated",
    "FacilityCode": null,
    "Logs": [
      {
        "AttemptID": "01986857-f4ef-728a-a296-7b3e71daeac7",
        "ID": "01986857-f4ef-7a0f-9ab4-d5fca3c7b6a7"
      }
    ],
    "Message": {
      "ID": 74085725083
    },
    "Source": {
      "ID": "cc98b497-28ec-4182-94e5-21315c4eb359",
      "Name": "Northwestern (Hippocratic AI) FHIR.Event.Scheduling (SIU) Source (s)"
    },
    "Test": true,
    "Transmission": {
      "ID": 73168642269
    }
  },
  "entry": [
	 ...
    {
      "fullUrl": "urn:uuid:7f1989e4-b009-4ff1-85fe-c526932970fd",
      "resource": {
        "comment": "pls call the patient",
        "end": "2025-07-31T15:00:00.000Z",
        "identifier": [
          {
            "type": {
              "coding": [
                {
                  "code": "FILL",
                  "display": "Filler Identifier",
                  "system": "<http://terminology.hl7.org/CodeSystem/v2-0203>"
                }
              ],
              "text": "Filler Identifier"
            },
            "value": "200212133596"
          }
        ],
        "participant": [
          {
            "actor": {
              "reference": "urn:uuid:f06c8769-6f61-449c-963e-9ad26f786c94",
              "type": "Practitioner"
            },
            "status": "accepted",
            "type": [
              {
                "text": "MD"
              }
            ]
          },
          {
            "actor": {
              "reference": "urn:uuid:220d2650-d662-4de7-a437-744a32b4448d",
              "type": "Patient"
            },
            "status": "accepted"
          }
        ],
        "reasonCode": [
          {
            "text": "GI COLONOSCOPY SCREENING OPEN ACCESS"
          }
        ],
        "resourceType": "Appointment",
        "serviceType": [
          {
            "coding": [
              {
                "code": "1400",
                "display": "COLONOSCOPY, SCREENING",
                "system": "urn:redox:cc98b497-28ec-4182-94e5-21315c4eb359:NMGEAP"
              }
            ],
            "text": "COLONOSCOPY, SCREENING"
          }
        ],
        "start": "2025-07-31T14:30:00.000Z",
        "status": "proposed"
      }
    }
  ],
  "id": "6e8bbd16-c210-467e-a07c-5ef3cbdbf9dd",
  "resourceType": "Bundle",
  "timestamp": "2025-08-02T01:14:11.635Z",
  "type": "message"
}
```

**Example 1: References selector**

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

**Example 1: Config modifier with references keyword**

```yaml
references:
  csnValue:
    use: initialPayload
    get: PATIENT[0].PID.18.1
if:
  operator: all
  terms:
    - use: csnValue
  then:
    concat:
      - {}
      - properties:
          value:
            use: csnValue
          type:
            constant:
              coding:
                - code: CSN
                  display: Contact Serial Number
                  system: Northwestern Medical HL7v2 Definition
              text: Contact Serial Number (CSN)
  else:
    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
{
  "Meta": {
    "DataModel": "FHIR.Event.Scheduling",
    "Destinations": [
      {
        "ID": "3156f0f2-d249-4970-b50f-afffc8021d71",
        "Name": "ICE_UAT_LISTENER"
      }
    ],
    "EventDateTime": null,
    "EventType": "scheduling-appointment-updated",
    "FacilityCode": null,
    "Logs": [
      {
        "AttemptID": "01986857-f4ef-728a-a296-7b3e71daeac7",
        "ID": "01986857-f4ef-7a0f-9ab4-d5fca3c7b6a7"
      }
    ],
    "Message": {
      "ID": 74085725083
    },
    "Source": {
      "ID": "cc98b497-28ec-4182-94e5-21315c4eb359",
      "Name": "Northwestern (Hippocratic AI) FHIR.Event.Scheduling (SIU) Source (s)"
    },
    "Test": true,
    "Transmission": {
      "ID": 73168642269
    }
  },
  "entry": [
	 ...,
    {
      "fullUrl": "urn:uuid:7f1989e4-b009-4ff1-85fe-c526932970fd",
      "resource": {
        "comment": "pls call the patient",
        "end": "2025-07-31T15:00:00.000Z",
        "identifier": [
          {
            "type": {
              "coding": [
                {
                  "code": "FILL",
                  "display": "Filler Identifier",
                  "system": "<http://terminology.hl7.org/CodeSystem/v2-0203>"
                }
              ],
              "text": "Filler Identifier"
            },
            "value": "200212133596"
          },
          {
            "type": {
              "coding": [
                {
                  "code": "CSN",
                  "display": "Contact Serial Number",
                  "system": "Northwestern Medical HL7v2 Definition"
                }
              ],
              "text": "Contact Serial Number (CSN)"
            },
            "value": "200212139694"
          }         
        ],
        "participant": [
          {
            "actor": {
              "reference": "urn:uuid:f06c8769-6f61-449c-963e-9ad26f786c94",
              "type": "Practitioner"
            },
            "status": "accepted",
            "type": [
              {
                "text": "MD"
              }
            ]
          },
          {
            "actor": {
              "reference": "urn:uuid:220d2650-d662-4de7-a437-744a32b4448d",
              "type": "Patient"
            },
            "status": "accepted"
          }
        ],
        "reasonCode": [
          {
            "text": "GI COLONOSCOPY SCREENING OPEN ACCESS"
          }
        ],
        "resourceType": "Appointment",
        "serviceType": [
          {
            "coding": [
              {
                "code": "1400",
                "display": "COLONOSCOPY, SCREENING",
                "system": "urn:redox:cc98b497-28ec-4182-94e5-21315c4eb359:NMGEAP"
              }
            ],
            "text": "COLONOSCOPY, SCREENING"
          }
        ],
        "start": "2025-07-31T14:30:00.000Z",
        "status": "proposed"
      }
    }
  ],
  "id": "6e8bbd16-c210-467e-a07c-5ef3cbdbf9dd",
  "resourceType": "Bundle",
  "timestamp": "2025-08-02T01:14:11.635Z",
  "type": "message"
}
```

## 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: 

1. Get the current OBX index (stored as `currentObxId`) from this loop.
2. 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
{
  "MSH": {
    "1": "|",
    "10": 74087159085,
    "12": {
      "1": "2.3"
    },
    "2": "^~\\&",
    "3": {
      "1": "REDOX"
    },
    "4": {
      "1": "RDX"
    },
    "6": {
      "1": "ZA300"
    },
    "7": {
      "1": "20250801183107"
    },
    "9": {
      "1": "ORU",
      "2": "R01"
    }
  },
  "PATIENT_RESULT": [
    {
      "ORDER_OBSERVATION": [
        {
          "NTE": [
          ],
          "OBR": {
            "1": 1,
            "13": null,
            "15": {
              "1": {
                "1": null
              },
              "4": {
                "1": null
              }
            },
            "16": [
              {
                "1": "1002198",
                "2": {
                  "1": "Alexander"
                },
                "3": "Mark",
                "7": null,
                "9": {
                  "1": null
                }
              }
            ],
            "2": {
              "1": "5000199677"
            },
            "22": {
              "1": "20250714150157"
            },
            "25": "P",
            "27": [
              {
                "6": null
              }
            ],
            "28": [
            ],
            "3": {
              "1": "5579782"
            },
            "4": {
              "1": "J774a",
              "2": "GenomeSeqDx (Trio)",
              "3": null
            },
            "7": {
              "1": "20250714160000"
            }
          },
          "OBSERVATION": [
            {
              "NTE": [
                ...
              ],
              "OBX": {
                "1": 1,
                "11": "P",
				...
            },
            {
              "NTE": [
              ],
              "OBX": {
                "1": 2,
                "11": "P",
                ...

              }
            },
            {
              "NTE": [
              ],
              "OBX": {
                "1": 3,
                "11": "P",
                ...
              }
            },
            {
              "NTE": [
              ],
              "OBX": {
                "1": 4,
                "11": "P",
                ...
              }
            },
            ...
            }
          ],
          "ORC": {
            "1": "RE",
            ...
          }
        }
      ],
      "PATIENT": {
        ...
      }
    }
  ]
}
```

**Example 2: References selector**

```json
$.PATIENT_RESULT[0].ORDER_OBSERVATION[*].OBSERVATION[*].OBX
```

**Example 2: Config modifier with references keyword**

```yaml
references:
  OBX: {}
  currentObxId:
    pipe:
      - use: '@parent'
        get: OBX.1
      - plugin:
          name: convert
          action: number-to-string
merge:
  - use: OBX
  - properties:
      '1':
        pipe:
          - use: initialPayload
            get: PATIENT_RESULT
            items:
              pipe:
                - get: ORDER_OBSERVATION
                  items:
                    pipe:
                      - get: OBSERVATION
                        plugin:
                          name: array
                          action: find
                          parametersIsProperty: true
                          parameters:
                            properties:
                              match:
                                properties:
                                  OBX.1:
                                    use: currentObxId
                      - get: OBX.1
                - plugin:
                    name: array
                    action: flatten
          - plugin:
              name: array
              action: flatten
          - 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
{
  "MSH": {
    "1": "|",
    "10": 74087159085,
    "12": {
      "1": "2.3"
    },
    "2": "^~\\&",
    "3": {
      "1": "REDOX"
    },
    "4": {
      "1": "RDX"
    },
    "6": {
      "1": "ZA300"
    },
    "7": {
      "1": "20250801183107"
    },
    "9": {
      "1": "ORU",
      "2": "R01"
    }
  },
  "PATIENT_RESULT": [
    {
      "ORDER_OBSERVATION": [
        {
          "NTE": [
          ],
          "OBR": {
            "1": 1,
            "13": null,
            "15": {
              "1": {
                "1": null
              },
              "4": {
                "1": null
              }
            },
            "16": [
              {
                "1": "1002198",
                "2": {
                  "1": "Alexander"
                },
                "3": "Mark",
                "7": null,
                "9": {
                  "1": null
                }
              }
            ],
            "2": {
              "1": "5000199677"
            },
            "22": {
              "1": "20250714150157"
            },
            "25": "P",
            "27": [
              {
                "6": null
              }
            ],
            "28": [
            ],
            "3": {
              "1": "5579782"
            },
            "4": {
              "1": "J774a",
              "2": "GenomeSeqDx (Trio)",
              "3": null
            },
            "7": {
              "1": "20250714160000"
            }
          },
          "OBSERVATION": [
            {
              "NTE": [
                ...
              ],
              "OBX": {
                "1": "1",
                "11": "P",
				...
            },
            {
              "NTE": [
              ],
              "OBX": {
                "1": "2",
                "11": "P",
                ...

              }
            },
            {
              "NTE": [
              ],
              "OBX": {
                "1": "3",
                "11": "P",
                ...
              }
            },
            {
              "NTE": [
              ],
              "OBX": {
                "1": "4",
                "11": "P",
                ...
              }
            },
            ...
            }
          ],
          "ORC": {
            "1": "RE",
            ...
          }
        }
      ],
      "PATIENT": {
        ...
      }
    }
  ]
}
```

## 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](https://docs.redoxengine.com/permalink/mq5Vxn2NXPe0mE4qjFiCW/#parent).