# `DosageInstruction`

How to take a medicine: a dose, a route and how often.

Use it for a prescription's directions, shown as `500 mg, Oral use, 2 times per 1 day`. For the amount alone, use [`Dose`](/docs/types/type-dose.md).

## Shape

| Field | Type | Required? |
|---|---|---|
| `dose` | [`Dose`](/docs/types/type-dose.md) | Yes |
| `route` | [`RouteOfAdministration`](/docs/types/type-route-of-administration.md) | Yes |
| `times` | `Int` | Yes |
| `per` | [`Duration`](/docs/types/type-duration.md) | Yes |
| `as_needed` | `Bool` | Yes |

## Example

```jadpo
DosageInstruction {
    dose: Dose.mass { amount: 500mg }
    route: RouteOfAdministration.oral
    times: 2
    per: 1d
    as_needed: false
}
```

## Good to know

- `times` must be at least 1, and `per` above nothing.
- `==` tells you whether two are the same. `<` and `list.sort_by` don't take it, so sort by one of its parts instead.

## In JSON

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

```json
{"dose":{"tag":"mass","amount":{"value":"0.0005","unit":"kg"}},"route":"oral","times":2,"per":"PT24H","as_needed":false}
{"dose":{"tag":"volume","amount":{"value":"0.00001","unit":"cubic_metre"}},"route":"oral","times":1,"per":"PT6H","as_needed":true}
{"dose":{"tag":"mass","amount":{"value":"0.00004","unit":"kg"}},"route":"subcutaneous","times":1,"per":"PT168H","as_needed":false}
```

## Details

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

`DosageInstruction` is in the group Health, 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 6 columns, each named for the field, `_` and its suffix. This is `{"dose":{"tag":"volume","amount":{"value":"0.00001","unit":"cubic_metre"}},"route":"oral","times":1,"per":"PT6H","as_needed":true}`:

| Column | Type | Holds |
|---|---|---|
| `<field>_dose_kind` | `text` | `'volume'` |
| `<field>_dose_amount` | `numeric(38, 9)` | `0.00001` |
| `<field>_route` | `text` | `'oral'` |
| `<field>_times` | `integer` | `1` |
| `<field>_per` | `bigint` | `21600000` |
| `<field>_as_needed` | `boolean` | `TRUE` |

### How it is shown to people

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

With `locale: Locale.en_gb`:

| Value | Shown |
|---|---|
| `{"dose":{"tag":"mass","amount":{"value":"500","unit":"mg"}},"route":"oral","times":2,"per":"PT24H","as_needed":false}` | `500 mg, Oral use, 2 times per 1 day` |
| `{"dose":{"tag":"volume","amount":{"value":"10","unit":"ml"}},"route":"oral","times":1,"per":"PT6H","as_needed":true}` | `10 ml, Oral use, 1 time per 6 hours, when needed` |
| `{"dose":{"tag":"mass","amount":{"value":"40","unit":"mg"}},"route":"subcutaneous","times":1,"per":"PT168H","as_needed":false}` | `40 mg, Subcutaneous use, 1 time per 7 days` |

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