Label Value Guidelines and Management

- The `com.docker.*`, `io.docker.*`, and `org.dockerproject.*` namespaces are reserved by Docker for internal use. - Label keys should begin and end with a lower-case letter and should only contain lower-case alphanumeric characters, the period character (`.`), and the hyphen character (`-`). Consecutive periods or hyphens aren't allowed. - The period character (`.`) separates namespace "fields". Label keys without namespaces are reserved for CLI use, allowing users of the CLI to interactively label Docker objects using shorter typing-friendly strings. These guidelines aren't currently enforced and additional guidelines may apply to specific use cases. ### Value guidelines Label values can contain any data type that can be represented as a string, including (but not limited to) JSON, XML, CSV, or YAML. The only requirement is that the value be serialized to a string first, using a mechanism specific to the type of structure. For instance, to serialize JSON into a string, you might use the `JSON.stringify()` JavaScript method. Since Docker doesn't deserialize the value, you can't treat a JSON or XML document as a nested structure when querying or filtering by label value unless you build this functionality into third-party tooling. ## Manage labels on objects Each type of object with support for labels has mechanisms for adding and managing them and using them as they relate to that type of object. These links provide a good place to start learning about how you can use labels in your Docker deployments. Labels on images, containers, local daemons, volumes, and networks are static for the lifetime of the object. To change these labels you must recreate the object. Labels on Swarm nodes and services can be updated dynamically. - Images and containers - [Adding labels to images](/reference/dockerfile.md#label) - [Overriding a container's labels at runtime](/reference/cli/docker/container/run.md#label) - [Inspecting labels on images or containers](/reference/cli/docker/inspect.md) - [Filtering images by label](/reference/cli/docker/image/ls.md#filter) - [Filtering containers by label](/reference/cli/docker/container/ls.md#filter) - Local Docker daemons - [Adding labels to a Docker daemon at runtime](/reference/cli/dockerd.md) - [Inspecting a Docker daemon's labels](/reference/cli/docker/system/info.md) - Volumes - [Adding labels to volumes](/reference/cli/docker/volume/create.md) - [Inspecting a volume's labels](/reference/cli/docker/volume/inspect.md) - [Filtering volumes by label](/reference/cli/docker/volume/ls.md#filter) - Networks - [Adding labels to a network](/reference/cli/docker/network/create.md) - [Inspecting a network's labels](/reference/cli/docker/network/inspect.md) - [Filtering networks by label](/reference/cli/docker/network/ls.md#filter) - Swarm nodes - [Adding or updating a Swarm node's labels](/reference/cli/docker/node/update.md#label-add) - [Inspecting a Swarm node's labels](/reference/cli/docker/node/inspect.md) - [Filtering Swarm nodes by label](/reference/cli/docker/node/ls.md#filter) - Swarm services - [Adding labels when creating a Swarm service](/reference/cli/docker/service/create.md#label) - [Updating a Swarm service's labels](/reference/cli/docker/service/update.md) - [Inspecting a Swarm service's labels](/reference/cli/docker/service/inspect.md) - [Filtering Swarm services by label](/reference/cli/docker/service/ls.md#filter)

This section details guidelines for label values, noting that they can be any string-represented data (e.g., JSON, XML), but Docker doesn't deserialize them. It also provides links to documentation on managing labels for various Docker objects (images, containers, daemons, volumes, networks, Swarm nodes, and Swarm services), including adding, inspecting, and filtering by labels. Labels are static for most objects but can be dynamically updated on Swarm nodes and services.