# Durations

A duration is a length of time, such as a timeout. In source it is always
a number and a unit, `500ms`, `30s`, `5m`, `2h` or `30d`. ISO 8601 text
(`"PT5M"`) is used only on the wire.

```jadpo
/// How long a request may take.
type RequestTimeout = Duration {
    max: 30s
}

/// How long a reminder comes before its due time.
type ReminderNotice = Duration {
    min: 1m
    max: 30d
}

test "durations are written with a unit, and add up" {
    var allowed: RequestTimeout = 5s
    assert allowed + 500ms == 5500ms
    var notice: ReminderNotice = 2h
    assert notice - 30m == 90m
}
```

`30d` means exactly 30 × 24 hours, which is what a retention period or a
token lifetime means. Moving a date by calendar days is a separate
operation on `CalendarDate` ([Zones and local times](zones-and-local-times.md)).

## On the wire

The runtime writes a duration as ISO 8601 in hours, minutes and seconds:
`"PT5M"`, `"PT1.5S"`, `"PT720H"` for `30d`, and `"-PT5M"` for a negative
one. A request's JSON, query string, path and headers send it the same way,
and days (`"P1DT2H"`) are accepted as 24 hours each. `5m` is the source's
spelling, and a request that sends it is refused.

A setting is the exception. It is read as source writes it, `5m`, and also
as the canonical ISO 8601 text, `PT5M`, as `text.parse` reads it, so a
value copied from a response or a log works as a setting too. Every
boundary reads a standard type the same way
([Every boundary through the contract](every-boundary-through-the-contract.md)).