> ## Documentation Index
> Fetch the complete documentation index at: https://datum-4926dda5-docs-api-reference-demo.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Field formats & types

> How to read the value types, formats, required markers, enums, and defaults used in every resource's field tables.

<Note>
  This is a resource-agnostic guide to the conventions used in the **Spec fields** and **Status fields** tables on every [API resource](/api/overview) page. It explains what the `Type` and `Required` columns mean and how formats are expressed — it does not describe any one resource. For examples, see a real page like [DNSZone](/api/dns/dnszone) or [HTTPRoute](/api/networking/gateway/httproute).
</Note>

<Warning>
  The Datum Cloud API is currently **alpha** (`v1alpha1`; the Gateway API resources are served at stable `v1`). Field types, formats, allowed values, and defaults may change in backward-incompatible ways between releases.
</Warning>

## The field tables

Every resource page lists its fields in two tables:

* **Spec fields** — the values you set to declare desired state. These have a `Required` column.
* **Status fields** — the values the platform populates to report observed state. These are read-only, so there is no `Required` column.

Fields are addressed by their dotted path from the top of the object, for example `spec.domainName` or `status.conditions`. A path segment that is itself an object continues with another dot (`spec.rules.matches.path.type`).

## Value types

The `Type` column uses a small, consistent vocabulary.

| Type                | Meaning                                                                                   | Example value                            |
| ------------------- | ----------------------------------------------------------------------------------------- | ---------------------------------------- |
| `string`            | A single text value.                                                                      | `"example.com"`                          |
| `integer`           | A whole number.                                                                           | `3`                                      |
| `boolean`           | `true` or `false`.                                                                        | `true`                                   |
| `[]type`            | A **list** of values of `type` (e.g. `[]string`, `[]Object`).                             | `["ns1.example.net", "ns2.example.net"]` |
| `Object`            | A **nested object** with its own fields, documented as deeper rows (`spec.parent.child`). | `{ name: "web", port: 443 }`             |
| `map[string]string` | A set of key/value pairs, such as labels or annotations.                                  | `{ env: "prod" }`                        |

<Note>
  A type shown as `Object` or `[]Object` is expanded by its own sub-rows in the same table (or on the same page). To see the complete, live field tree for any resource — including every nested object — run `datumctl explain <resource> --recursive`. See [Discovering resources & schemas](/datumctl/discovering-resources).
</Note>

### Lists (`[]type`)

A `[]type` field accepts zero or more entries. In YAML it is written as a block sequence:

```yaml theme={null}
spec:
  nameservers:
    - ns1.example.net
    - ns2.example.net
```

`[]Object` lists hold structured entries; each entry has the sub-fields documented for that object.

### Nested objects

An `Object` field groups related sub-fields under one key. The field tables document each sub-field on its own row using the full dotted path, so `spec.parent` (type `Object`) is followed by rows like `spec.parent.name` and `spec.parent.port`.

## Formatted strings

Some `string` fields carry an additional **format** — a syntax the value must follow. The field's description states the format; common ones include:

* **RFC 3339 timestamp** — a UTC date-time such as `2026-07-01T14:30:00Z`. All timestamp fields (for example a resource's `metadata.creationTimestamp`) use [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339) form. These are read-only; clients do not set them.
* **RFC 1123 name** — the `metadata.name` of most resources must be a lowercase [RFC 1123](https://www.rfc-editor.org/rfc/rfc1123) label: lowercase alphanumerics and `-`, starting and ending with an alphanumeric (for example `example-com`).
* **RFC 1123 hostname / FQDN** — domain-shaped fields (for example a zone's domain name) use dot-separated RFC 1123 labels, such as `example.com`.
* **Duration** — a Go-style duration string such as `30s`, `5m`, or `1h`.
* **Quantity** — a resource amount such as `500m`, `2Gi`, or `100`.

<Tip>
  When a field's exact format matters, read its live description with `datumctl explain <resource>.<field>` — the schema is the source of truth for the format rules.
</Tip>

## How markers are shown

### Required

The **`Required`** column marks whether you must supply a spec field.

| Value          | Meaning                                               |
| -------------- | ----------------------------------------------------- |
| `Yes`          | You must set this field for the resource to be valid. |
| *(blank / No)* | The field is optional.                                |

Every resource also requires the standard identifiers (`apiVersion`, `kind`, and `metadata.name`); these are assumed on every page and not repeated in the spec table.

### Enums (allowed values)

When a field accepts only a fixed set of values, those values are listed in the field's description. For example, an HTTP route path-match `type` accepts `Exact`, `PathPrefix`, or `RegularExpression` — any other value is rejected on apply.

<Note>
  `datumctl explain` surfaces these under an **`ENUM:`** heading, and the API rejects out-of-range values at apply time.
</Note>

### Defaults

If an optional field is omitted, the platform may apply a **default** value. When a field has a default, the page notes it in the field's description (for example, "defaults to `PathPrefix`"). A field with no documented default is simply left unset when omitted — read the resulting value back from status or with `datumctl get -o yaml`.

## Reading vs. writing fields

* **Spec** fields are yours to set. Change them declaratively and re-apply — see [Changing resources](/datumctl/resources/changing) and [Safe changes & declarative config](/datumctl/resources/safe-changes).
* **Status** fields are populated by the platform and are read-only. Inspect them with [Reading resources](/datumctl/resources/reading) and control the shape of the output with [Output formats & scripting](/datumctl/output-and-scripting).

## Scope: Project vs. Platform

Each resource's **Identity** table lists a **Scope** of either **Project** (the resource lives inside a project) or **Platform** (it is shared across the platform). Scope determines which context a command runs against — see [Contexts & scoping](/datumctl/contexts-and-scoping).

<Info>
  A resource's `metadata` may include a `namespace` field, but you never choose it directly. Datum Cloud scoping is expressed as **Project** or **Platform**; the CLI resolves the underlying `namespace` field from your active context.
</Info>

## Related

* [API conventions](/api/concepts/conventions) — the `apiVersion`/`kind`/`metadata`/`spec`/`status` model these field tables describe.
* [Object metadata](/api/concepts/metadata) — the shared `metadata` fields, including the `name` format and label/annotation maps.
* [Validation & safe changes](/api/concepts/validation) — how the API enforces these types, formats, enums, and required markers on write.
* [Resource references](/api/concepts/references) — the reference-object convention used by `Ref`/`Refs` fields.
* [Reading resources](/datumctl/resources/reading) and [Output formats & scripting](/datumctl/output-and-scripting) — inspect field values with the CLI.
* [Discovering resources & schemas](/datumctl/discovering-resources) — explore live field types with `datumctl explain`.