# prefer

## Definition

In a config modifier schema, use `prefer` to specify which value to return when evaluating an array of property definitions. If the specified `prefer` value exists, it's returned, otherwise the next property is evaluated. 

This is useful for common situations when there are multiple possible fields from the input that might be relevant to the output, and you want to choose the “best” from that list.

> **Exclusive keywords**
>
> If `properties`, `if`, `concat`,  `switch`, `pipe`, `merge`, `prefer`, or `items` are present at the same nesting level, only the first keyword listed will run. We recommend not listing these keywords together at the same nesting level. 

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

You’re receiving an ADT^02 message where `Visit.VisitDateTime` is normally mapped from PV1.44.1 but is sometimes `null` or doesn’t exist. However, you still want to map a value from `PV2.8.1` as a backup. This is a perfect use case for `prefer`. If the first choice is `null` or missing, the schema automatically falls back to the second, third, or Nth choice.

> **Definition of existence**
>
> We define <u>existence</u> of a value based on some rules. Specifically, these evaluations are defined as <u>does not exist</u>:
>
> - `undefined`
> - `null`
> - `''`
> - `[]`
> - `NaN`
>
> We specifically treat some Falsy ([learn about Falsy](https://developer.mozilla.org/en-US/docs/Glossary/Falsy)) values as <u>exists</u>:
>
> - `false`
> - `0`
> - `' '` (empty string but padded with a space)

**Example: Prefer input from initial payload**

```json
  {
    "PV1": {
    "1": "1",
    "2": "P",
    "3": {
      "1": "2EAE",
      "2": "",
      "3": "",
      "4": {
        "1": "HMC"
      },
      "5": "",
      "6": "",
      "7": "HMC"
    },
    "4": "Elective",
    "7": [
      {
        "1": "",
        "2": {
          "1": "Zconnected"
        },
        "3": "PhysOrthopaedicSurg",
        "4": "",
        "5": "",
        "6": "",
        "7": "",
        "8": "",
        "9": {
          "1": ""
        },
        "10": "PRSNL"
      }
    ],
    "10": "ORS",
    "14": "Non-Health Care Fac",
    "18": "B",
    "20": [
      {
        "1": "Self-pay"
      }
    ],
    "39": "HMC^HMC MHMC^ADT",
    "41": "P"
  },
  "PV2": {
    "3": {
      "1": "",
      "2": "arthritis"
    },
    "8": {
      "1": "20251215073000"
    }
  }
}
```

**Example: Prefer selector**

```json
$.Visit.VisitDateTime
```

**Example: Config modifier with prefer keyword**

```yaml
pipe:
  - use: initialPayload
    prefer:
      - get: PV1.44.1
      - get: PV2.8.1
  - plugin:
      name: date-time
      action: parse
      parameters:
        standard: HL7
```

Based on this example config modifier schema, this is the output.

**Example: Prefer output in processed payload**

```json
{
  ...
  "Visit": {
    ...
    "VisitDateTime": "2025-12-15T07:30:00.000Z"
  }
}
```