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

# Object metadata

> The shared metadata block every Datum Cloud resource carries — name, labels, annotations, and the system-managed fields you never set.

<Note>
  This is a resource-agnostic concept page. Every Datum Cloud resource — a [DNSZone](/api/dns/dnszone), an [HTTPRoute](/api/networking/gateway/httproute), a Project, and so on — carries the same `metadata` block, so individual resource pages omit it and link here instead.
</Note>

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

## Overview

Every resource you create or read has three top-level sections: `metadata`, `spec`, and `status`. The `spec` and `status` sections are specific to each resource kind, but `metadata` is shared and looks the same everywhere:

```yaml theme={null}
apiVersion: dns.networking.miloapis.com/v1alpha1
kind: DNSZone
metadata:
  name: example-com
  labels:
    team: platform
    env: production
  annotations:
    datum.net/change-ticket: "OPS-1421"
spec:
  # ...resource-specific fields
```

`metadata` holds the resource's identity (its name), the labels and annotations you use to organize and describe it, and a set of system-managed fields the platform maintains for you.

## Fields you set

These are the metadata fields you provide when creating or changing a resource.

| Field                  | Type               | Description                                                                                                                                                                |
| ---------------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `metadata.name`        | string             | The resource's name. Required at creation (unless the resource supports server-generated names). Must be unique within its scope and **cannot be changed** after creation. |
| `metadata.labels`      | map\[string]string | Key/value pairs used to organize, group, and select resources. Ideal for querying and filtering.                                                                           |
| `metadata.annotations` | map\[string]string | Key/value pairs for arbitrary, non-identifying metadata — often set by tools or automation. Not used for selection or filtering.                                           |

### Name

`name` identifies the resource within its scope. A [Project-scoped](/datumctl/contexts-and-scoping) resource's name must be unique among resources of the same kind in that Project; a Platform-scoped resource's name must be unique across the platform. Names are set once, at creation, and cannot be updated afterward — to "rename" a resource you delete it and create a new one.

Names follow the standard DNS-compatible naming rules ([RFC 1123](https://datatracker.ietf.org/doc/html/rfc1123)): lowercase alphanumeric characters and `-`, starting and ending with an alphanumeric character (for example, `example-com`).

<Tip>
  Some resources let the server generate a unique name for you instead of requiring one. When supported, you supply a name prefix and the platform appends a unique suffix. Check a resource's schema with `datumctl explain <resource>.metadata` — see [Discovering resources & schemas](/datumctl/discovering-resources).
</Tip>

### Labels

Labels are key/value pairs meant to be **queried and selected on**. Use them to attach identifying dimensions — team ownership, environment, application, tier — that you'll later want to filter by:

```yaml theme={null}
metadata:
  labels:
    team: platform
    env: production
    app: checkout
```

Because labels are indexed for selection, keep the set small and stable, and use them for values you actually filter on. See [Reading resources](/datumctl/resources/reading) and [Output formats & scripting](/datumctl/output-and-scripting) for filtering and label-selector usage.

### Annotations

Annotations are also key/value pairs, but they are for **arbitrary metadata that is not queried** — longer descriptions, tool state, change-ticket references, contact info, or data that automation reads and writes. They are not used for selection or filtering, so there's no penalty for larger or more free-form values.

```yaml theme={null}
metadata:
  annotations:
    datum.net/managed-by: "terraform"
    datum.net/change-ticket: "OPS-1421"
```

<Note>
  **Labels vs. annotations:** if you want to *find or group* resources by a value, use a label. If you just want to *attach* information to a resource, use an annotation.
</Note>

## Fields the platform manages

The platform populates and maintains the following fields automatically. They are **read-only** — do not set them in your manifests. They appear when you read a resource (for example with `datumctl get -o yaml`), and are useful for inspection and automation.

| Field                        | Type      | Description                                                                                                                                                                                                                                    |
| ---------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `metadata.uid`               | string    | A globally unique identifier assigned at creation. Unlike `name`, it never changes and is never reused, so it unambiguously identifies one specific instance of a resource over time.                                                          |
| `metadata.creationTimestamp` | string    | RFC 3339 / UTC timestamp of when the resource was created.                                                                                                                                                                                     |
| `metadata.generation`        | integer   | A counter that increments each time the resource's `spec` (desired state) changes. Controllers compare it against a resource's observed generation to tell whether the platform has caught up to your latest change.                           |
| `metadata.resourceVersion`   | string    | An opaque version token that changes on every update. Used internally for change detection and safe concurrent updates. Treat it as opaque — never edit it.                                                                                    |
| `metadata.deletionTimestamp` | string    | Set by the platform when a resource is being deleted. Once set, the resource is scheduled for removal after any outstanding cleanup completes.                                                                                                 |
| `metadata.finalizers`        | \[]string | A list of cleanup tasks that must finish before the resource is fully removed. While the list is non-empty, deletion is held so dependent cleanup (releasing addresses, tearing down backing infrastructure) can run. Managed by the platform. |

<Warning>
  Don't copy these fields into a manifest you're applying. If you save a resource with `datumctl get -o yaml` and re-apply it, strip the system-managed metadata (and the entire `status` block) first — leaving `resourceVersion` in, for example, can cause an apply to be rejected. See [Safe changes & declarative config](/datumctl/resources/safe-changes).
</Warning>

## The namespace field

You may notice a `metadata.namespace` field when you inspect a resource. In Datum Cloud you don't manage namespaces directly — the user-facing scoping concept is the **Project** (or the **Platform**, for shared resources). Your active context determines where a resource lives, and the CLI sets scope with the `--project` flag rather than a namespace field you fill in by hand. See [Contexts & scoping](/datumctl/contexts-and-scoping).

## Working with metadata

* **Read it:** `datumctl get <resource> <name> -o yaml` shows the full `metadata` block, including the system-managed fields. See [Reading resources](/datumctl/resources/reading).
* **Change it:** set `name`, `labels`, and `annotations` in your manifest and apply with `datumctl apply -f`. See [Changing resources](/datumctl/resources/changing).
* **Explore it:** `datumctl explain <resource>.metadata` prints the live schema for the metadata block. See [Discovering resources & schemas](/datumctl/discovering-resources).

<Tip>
  Run `datumctl explain <resource>.metadata --recursive` to see the full, live metadata field tree for any resource.
</Tip>

## Related

* [API conventions](/api/concepts/conventions) — where `metadata` sits in the `apiVersion`/`kind`/`spec`/`status` model.
* [Scopes](/api/concepts/scopes) — why a `name` must be unique within its Project or across the Platform.
* [Status & conditions](/api/concepts/status-and-conditions) — how `metadata.generation` is compared against a condition's `observedGeneration`.
* [Field formats & types](/api/concepts/field-formats) — the RFC 1123 rules for `name` and the map types used by labels and annotations.
* [Reading resources](/datumctl/resources/reading) and [Changing resources](/datumctl/resources/changing) — read and set metadata with the CLI.
* [Contexts & scoping](/datumctl/contexts-and-scoping) — how the CLI resolves the `namespace` field from your active context.