Field formats & types

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

This is a resource-agnostic guide to the conventions used in the Spec fields and Status fields tables on every API resource 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 or HTTPRoute.

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.

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" }

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.

Lists ([]type)

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

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

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.

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.

datumctl explain surfaces these under an ENUM: heading, and the API rejects out-of-range values at apply time.

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 and Safe changes & declarative config.
• Status fields are populated by the platform and are read-only. Inspect them with Reading resources and control the shape of the output with Output formats & 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.

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.

Related

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