> For the complete documentation index, see [llms.txt](https://flapjax.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://flapjax.gitbook.io/docs/rest-api/guides/reference-normalisation.md).

# Reference normalisation

When you set a relationship attribute (one that links to a Person or another Stack), the API automatically normalises plain values into an explicit identifier format. This means you can pass simple values without having to manually wrap them.

## What Gets Normalized

Relationship attributes accept references to other entities. You can pass these references as simple strings or numbers, and the API wraps them for you:

| What You Send                      | What the API Uses                                        |
| ---------------------------------- | -------------------------------------------------------- |
| `"ext-123"`                        | `{"external_id": "ext-123"}`                             |
| `123` (on a Person-type attribute) | `{"external_id": "123"}`                                 |
| `["user-1", "user-2"]`             | `[{"external_id": "user-1"}, {"external_id": "user-2"}]` |
| `{"external_id": "ext-123"}`       | Passed through unchanged                                 |
| `{"internal_id": "..."}`           | Passed through unchanged                                 |

## Person-Type vs Stack-Type Attributes

The normalization behavior differs slightly based on the attribute type:

* **Person-type attributes**: Both strings and numbers are converted. A numeric value like `123` becomes `{"external_id": "123"}`.
* **Stack-type attributes**: Only strings are converted. Numeric values are passed through as-is without wrapping.

## Whitespace Handling

String values inside relationship references are automatically trimmed. For example:

```json
{ "customer": "  user-001  " }
```

becomes:

```json
{ "customer": {"external_id": "user-001"} }
```

The same trimming applies to `external_id` values inside explicit identifier objects.

## Empty and Nil Values

* Empty strings (`""`) and whitespace-only strings (`" "`) are normalized to `nil` — the relationship is cleared.
* `nil` values are passed through as `nil`.
* Boolean attributes with `nil` values are automatically set to `false`.

## Example

Suppose you have a "customer" attribute on an Orders stack that links to a Person. All of these are equivalent:

```json
{ "customer": "user-001" }
```

```json
{ "customer": {"external_id": "user-001"} }
```

Both result in the same relationship link to the person with external ID `user-001`.

For arrays (multi-value relationships), you can mix formats:

```json
{ "assigned_to": ["user-001", {"internal_id": "a1b2c3d4-..."}, "user-003"] }
```

Each element is normalized individually.