# `PersonName`

A person's name: a given name and, if they have one, a family name.

Use it wherever you store or show what someone is called, such as a customer on an order or the person a letter is addressed to. It keeps the two parts apart, so `text.format` can write them in the order the reader's language expects. For the name someone signs in with, use [`Username`](/docs/types/type-username.md). For one part on its own, use [`GivenName`](/docs/types/type-given-name.md) or [`FamilyName`](/docs/types/type-family-name.md). Any of the three is personal data with no `personal:` on the field: it counts as `PersonalData.identifying`.

## Shape

| Field | Type | Required? |
|---|---|---|
| `given` | [`GivenName`](/docs/types/type-given-name.md) | Yes |
| `family` | [`FamilyName`](/docs/types/type-family-name.md) | No |

Write every field when you build one, and give a field that isn't required as `none`.

## Example

```jadpo
PersonName { given: "Mary" family: "Somerville" }
```

## Good to know

- Some people have only one name, as Sukarno did. Give it as `given`, with `family: none`.
- It has no single text form, so `text.from` won't take it. Show it with `text.format(name, locale: locale)`, which gives "Mary Somerville" in English and puts the family name first in Japanese.
- `==` tells you whether two are the same. `<` and `list.sort_by` don't take it, so sort by one of its parts instead.
- A field that holds one counts as personal data (`identifying`), so you don't mark it yourself.

## In JSON

An object of its parts, in a request, a response or `json.write`:

```json
{"given":"Mary","family":"Somerville"}
{"given":"Sukarno","family":null}
```

When you read one, a field that isn't required may be left out, or sent as `null`.

## Details

<details>
<summary>Text form, storage, how it is shown, and operations</summary>

`PersonName` is in the group People and contact, and has been in Jadpo since 0.1.0.

### Text form

It has no single text form, so `text.from` and `text.parse` don't take it.

### How it is stored

It is stored in 2 columns, each named for the field, `_` and its suffix. This is `{"given":"Sukarno","family":null}`:

| Column | Type | Holds |
|---|---|---|
| `<field>_given` | `text` | `'Sukarno'` |
| `<field>_family` | `text` | `NULL::text` |

### How it is shown to people

`text.format(value, locale:)` shows it to people in their locale.

With `locale: Locale.en_gb`:

| Value | Shown |
|---|---|
| `{"given":"Mary","family":"Somerville"}` | `Mary Somerville` |
| `{"given":"Sukarno","family":null}` | `Sukarno` |

### Operations

It also takes `text.format`, `json.read`, `json.write` and `==`. [How every standard type behaves](/docs/every-standard-type-meets-one-contract.md) says how they work.

</details>