Alignment/Consolidation of Predefined Annotations to Support Artifact Types

[sabre1041]

Currently, there is guidance on the set of predefined annotation keys that can be placed upon the different types. However, with the addition of artifact type, there are only two annotations that are explicitly documented.

• org.opencontainers.artifact.created
• org.opencontainers.artifact.description

The majority of the annotations prefixes which are currently documented using the org.opencontainers.image.* would also apply to artifacts in addition to the two that were previously documented.

Updated guidance and documentation is needed if indeed these same keys also apply to artifact types.

[imjasonh]

This specification defines the following annotation keys, intended for but not limited to image index, image manifest, artifact, and descriptor authors.

I interpret this to mean that all the annotations can be used for images, artifacts, indexes, and descriptors. It's a bit of an unfortunate misnomer, but I think we should interpret the spec to mean that, e.g., org.opencontainers.image.documentation is still usable by an artifact manifest.

If there's wording you think could help make this clearer, feel free to propose some here or send a PR.

[sudo-bmitch]

I had briefly considered duplicating the annotations for artifacts, but that felt worse than using the image annotations for artifacts. It's more work for consumers to search multiple names and handle conflicts if both are defined. So I agree with @imjasonh that using the image annotations for artifacts is a valid use.

[sabre1041]

@sudo-bmitch @imjasonh Perfect, and it aligns with my thoughts as well.

As for the documentation, propose that the annotations be modified to a form similar to org.opencontainers.<type>.created and defining the valid types explicitly beforehand (ie image and artifact).

Thoughts?

[sajayantony]

Duplication of annotations also makes conversions harder. Don’t see any concern reusing the defined annotations for multiple manifest even though they are under .image.

[sajayantony]

@sabre1041 - Do we need additional verbiage now since the both manifests now have an artifactType and with #1078 avoids the duplicates. Basically trying to close out all issue in the v1.1 milestone.

As per annotations.md

---

This specification defines the following annotation keys, intended for but not limited to image index, image manifest, and descriptor authors.

[jdolitsky]

this may not make any sense after #999 ? should we close?

[tianon]

I agree; I would personally have used the existing annotations for artifacts too, and having consolidated artifacts under the image manifest makes that seem even more correct. 😅

[sabre1041]

Closing as artifact specific annotations have been removed, thus there is no longer any overlap to support consolidation