Documentation Index
Fetch the complete documentation index at: https://tally.wharflab.com/llms.txt
Use this file to discover all available pages before exploring further.
A multi-pair LABEL block reads better when keys appear in a stable, logical
order. This rule reorders pairs inside a single LABEL instruction so that
related image metadata stays grouped and diffs stay small.
| Property | Value |
|---|
| Severity | Info |
| Category | Style |
| Default | Enabled |
| Auto-fix | Yes (in-block) |
Description
Image metadata reads best when keys cluster by purpose. The default
oci-logical order follows how reviewers usually scan a LABEL block:
| Group | Keys |
|---|
| 1. Identity | org.opencontainers.image.title, org.opencontainers.image.description |
| 2. Source / refs | org.opencontainers.image.source, org.opencontainers.image.url, org.opencontainers.image.documentation |
| 3. Ownership / legal | org.opencontainers.image.authors, org.opencontainers.image.vendor, org.opencontainers.image.licenses |
| 4. Release / provenance | org.opencontainers.image.version, org.opencontainers.image.revision, org.opencontainers.image.created, org.opencontainers.image.ref.name |
| 5. Base image | org.opencontainers.image.base.name, org.opencontainers.image.base.digest |
| 6. OpenShift / Kubernetes catalog | io.k8s.display-name, io.k8s.description, io.openshift.tags, io.openshift.expose-services, io.openshift.s2i.scripts-url |
| 7. Docker ecosystem | com.docker.image.source.entrypoint, com.docker.extension.* |
| 8. Legacy | org.label-schema.*, maintainer |
| 9. Unknown reverse-DNS | preserved or namespace-clustered (see sort-unknown) |
| 10. Unknown unqualified | preserved |
lexical order is a flat alphabetical comparator across all keys.
The rule reports when a single multi-pair LABEL instruction has at least two
pairs and the configured comparator says they are not in stable order.
Auto-fix
The fix swaps the source text of individual key=value spans inside the
existing LABEL, leaving continuation backslashes, indentation, and any
surrounding whitespace untouched. Per-pair edits are narrow on purpose so they
can co-run with tally/labels/prefer-grouped
and tally/newline-per-chained-call
without conflicts.
The fix is suppressed when:
- The
LABEL is single-line multi-pair. Let
tally/newline-per-chained-call split
it onto continuation lines first; the next lint pass then reorders.
- A comment line splits the pairs. Comments mark intentional sections, and the
v1 fixer never crosses them.
- The block contains a duplicate key. Defer to
tally/labels/no-duplicate-keys;
reordering duplicates would change the effective image metadata.
- A pair has a dynamic key, an empty key, an expansion error, or uses the
legacy
LABEL key value form.
Examples
Bad
FROM alpine:3.20
LABEL org.opencontainers.image.description="example image" \
org.opencontainers.image.source="https://github.com/example/demo" \
org.opencontainers.image.title="demo"
Good
FROM alpine:3.20
LABEL org.opencontainers.image.title="demo" \
org.opencontainers.image.description="example image" \
org.opencontainers.image.source="https://github.com/example/demo"
Configuration
[rules.tally.labels.prefer-stable-order]
severity = "info"
order = "oci-logical"
sort-unknown = false
| Option | Type | Default | Description |
|---|
order | "oci-logical" | "lexical" | "oci-logical" | Comparator. "oci-logical" clusters keys by purpose. "lexical" sorts purely alphabetically. |
sort-unknown | boolean | false | When true, group 9 (unknown reverse-DNS keys) is clustered by namespace and sorted lexically within each namespace. When false, those keys keep their relative source order. Groups 1–8 are unaffected because their ordering is already fully specified, and group 10 (unqualified unknown keys) always preserves source order. |