ContainerImagesLabels
This is a proposed Change for Fedora Linux.
This document represents a proposed Change. As part of the Changes process, proposals are publicly announced in order to receive community feedback. This proposal will only be implemented if approved by the Fedora Engineering Steering Committee.
Summary 
The org.opencontainers.image.name and org.opencontainers.image.license labels in Fedora container images get changed to org.opencontainers.image.title and org.opencontainers.image.licenses to more closely align with [The OpenContainers Annotations Spec The OpenContainers Annotations Spec].
Owner
- Name: [[User:adelton| Jan Pazdziora]]
- Email: adelton@fedoraproject.org
Detailed Description
Starting with Fedora 40, the Fedora container images contain labels in the org.opencontainers.image namespace:
$ skopeo inspect --config docker://registry.fedoraproject.org/fedora:39 | jq .config.Labels
{
"license": "MIT",
"name": "fedora",
"vendor": "Fedora Project",
"version": "39"
}
$ skopeo inspect --config docker://registry.fedoraproject.org/fedora:40 | jq .config.Labels
{
"io.buildah.version": "1.39.2",
"license": "MIT",
"name": "fedora",
"org.opencontainers.image.license": "MIT",
"org.opencontainers.image.name": "fedora",
"org.opencontainers.image.url": "https://fedoraproject.org/",
"org.opencontainers.image.vendor": "Fedora Project",
"org.opencontainers.image.version": "40",
"vendor": "Fedora Project",
"version": "40"
}
They seem to be modeled after [The OpenContainers Annotations Spec The OpenContainers Annotations Spec]. That specification is about image manifest annotations and not about labels per se, yet the similarity is very close.
The specification however does not list org.opencontainers.image.name and org.opencontainers.image.license, instead it mentions org.opencontainers.image.title and org.opencontainers.image.licenses.
The proposal is to change the labels to match the annotation specification to align with the specās guidance:
Keys using the org.opencontainers.image namespace are reserved for use in the OCI Image Specification and MUST NOT be used by other specifications and extensions, including other OCI specifications.
Feedback
In Making sure you're not a bot!, Neal suggested to add the new (correct) labels but keep the old ones as well. The problem is that the labels get inherited by any layered image which uses Fedora base images. And tools like docker build do not make it easy to remove the labels. You can overwrite them one by one but getting rid of them is not directly supported. So we are forcing maintainers of layered images to deal with (overwrite) labels that shouldnāt even be there to start with. I actually started digging into the issue because I noticed "org.opencontainers.image.name": "fedora" in our FreeIPA container images (GitHub - freeipa/freeipa-container: FreeIPA server in containers ā images at https://quay.io/repository/freeipa/freeipa-server?tab=tags).
We can add the correct labels org.opencontainers.image.title and org.opencontainers.image.licenses to Fedora 42 and 43 images before Fedora 44 release, so that any dependency / tooling can adapt and start using them with the released images.
In Making sure you're not a bot!, Neal asked if the non-namespaced legacy labels should be dropped as part of this change. Jan does not have a preference and would welcome other (FESCO) opinions ā the legacy labels have been around much longer so chances that something somewhere depends on them is much bigger; on the other hand, the overall move seems to be towards annotations and not labels, so it does not really matter if the legacy labels stay there.
Benefit to Fedora
This change makes Fedora better align with existing external specification.
Scope
- Proposal owners:
** PR Making sure you're not a bot! should be all that is needed to get this change in.
** PRs against Fedora 43 and 42 can be filed to add the correct labels but not remove the.nameand.license, so that any setup or tooling can start using them on the released container images, making migration easier. - Other developers:
** If other developerās packages or tooling depend on theorg.opencontainers.image.nameandorg.opencontainers.image.licenselabels in Fedora base container images, they will need to adapt to the new names. - Release engineering: [Making sure you're not a bot! #Releng issue number]
** IIUIC, no releng work is needed. - Policies and guidelines: N/A (not needed for this Change)
- Trademark approval: N/A (not needed for this Change)
- Alignment with the Fedora Strategy:
** TL;DR
Upgrade/compatibility impact
Any setup which relies on the org.opencontainers.image.name and org.opencontainers.image.license container image labels will need to be updated.
Early Testing (Optional)
Do you require āQA Blueprintā support? No.
How To Test
Pull fresh registry.fedoraproject.org/fedora:rawhide image by your podman, docker, docker-compose, or Kubernetes workload and see it working as it did before, even if the two labels have changed.
User Experience
No user visible behaviour change.
Dependencies
None.
Contingency Plan
- Contingency mechanism: (What to do? Who will do it?) Nothing bad happens if this change is not merged for the release, it just wonāt get done.
- Contingency deadline: N/A
- Blocks release? No
Documentation
N/A
Release Notes
\n
Last edited by @alking 2026-01-05T17:04:45Z
Last edited by @alking 2026-01-05T17:04:45Z
instead of reiterating. You can even do this by email, by replying with the heart emoji or just ā+1ā. This will make long topics easier to follow.