# Record sets

How names, record types, values and TTLs make up the record sets of a hosted zone, and the rules every write is checked against.

A record set is every value at one name and type, with one TTL: the three `A` addresses of
`www.example.com` are one set, its `TXT` values another. A zone holds at most one set per name and
type.

## Names

| You write         | It means                                                                      |
| ----------------- | ----------------------------------------------------------------------------- |
| `@`, or nothing   | The zone apex, `example.com`                                                  |
| `www`             | `www.example.com`                                                             |
| `www.example.com` | Taken as it is, because it is inside the zone                                 |
| `*.dev`           | A wildcard: every name under `dev.example.com` that has no records of its own |

Names are stored lowercase, fully qualified and without a trailing dot. A label may start with `_`
(`_dmarc`, `_acme-challenge`), and only the first label may be `*`. A name that is not a valid name
in the zone is refused with `400` "… is not a valid name in example.com".

## Types and values

Values are written one per line in the console, or as a list in the API, in the format below.
Duplicate values are merged; a set holds at most 100 values of at most 4,096 characters each.

| Type    | Value                                                     | Rules                                                                          |
| ------- | --------------------------------------------------------- | ------------------------------------------------------------------------------ |
| `A`     | `192.0.2.10`                                              | An IPv4 address                                                                |
| `AAAA`  | `2001:db8::10`                                            | An IPv6 address                                                                |
| `CNAME` | `target.example.net`                                      | Exactly one value; not at the apex; the only set at its name                   |
| `MX`    | `10 mail.example.com`                                     | Priority (0 to 65535) and mail host                                            |
| `TXT`   | `v=spf1 -all`                                             | Up to 4,096 characters                                                         |
| `NS`    | `ns1.example.net`                                         | Delegates a name below the apex; the apex `NS` set is the platform nameservers |
| `SRV`   | `10 5 5060 sip.example.com`                               | Priority, weight, port and target                                              |
| `CAA`   | `0 issue letsencrypt.org`                                 | Flags `0` or `128`, tag `issue`, `issuewild` or `iodef`, then the value        |
| `ALIAS` | An app, load balancer, bucket website or CDN distribution | No values; see [Point a name at a resource](point-a-name-at-a-resource.md)     |

Host names in `CNAME`, `NS`, `MX` and `SRV` values are stored lowercase, without a trailing dot.

## Writing a set

- **Add** (`POST …/records`, `dcloud dns records set`, **Add record**) creates the set at a name and
  type, or replaces the whole set that is there: its values, its TTL, its target, its health check
  and its routing. Whatever the request leaves out is gone afterwards.
- **Edit** (`PUT …/records/{recordId}`, `dcloud dns records update`, **Edit record**) changes one set;
  fields you leave out keep their stored value. The name and type of a set never change.
- A `CNAME` is refused next to any other set at its name, and any other type is refused at a name
  that has a `CNAME`. Adding a `CNAME` where one already exists is refused too: edit it instead.

See [Add a record](add-a-record.md) and [Edit or delete a record](edit-or-delete-a-record.md).

## TTL

The TTL is how many seconds resolvers may cache the set, from 1 to 604800.

| Where the set is written    | TTL when you give none                 |
| --------------------------- | -------------------------------------- |
| Console, **Add record**     | The form starts at 3600                |
| API, CLI and Terraform, add | 300, also when the add replaces a set  |
| Edit, any interface         | The stored TTL is kept                 |
| Zone file import            | 300 until the file's first `$TTL` line |

Some sets are served with a shorter TTL than the stored one: at most 60 seconds for a set with a
health check or with health-checked routing variants, and at most 30 seconds for an `ALIAS` to a
CDN distribution. The apex `SOA` and `NS` sets are served with 3600.

## Wildcards

A wildcard set answers for the names under it that have no records of their own. A name that has
any record set, of any type, or that has names with records below it, is not answered from the
wildcard.

## Limits

A zone holds at most the number of record sets its quota allows (see [Quotas](quotas.md)). Editing
a set or replacing one never counts against it.

## Related

- [Add a record](add-a-record.md)
- [How the nameservers answer](how-the-nameservers-answer.md)
