feat: add metadata.annotations to package schema (#3319)

Signed-off-by: Austin Abro <[email protected]>

src/api/v1alpha1/package.go

@@ -170,6 +170,9 @@ type ZarfMetadata struct {
 	Vendor string `json:"vendor,omitempty"`
 	// Checksum of a checksums.txt file that contains checksums all the layers within the package.
 	AggregateChecksum string `json:"aggregateChecksum,omitempty"`
+	// Annotations contains arbitrary metadata about the package.
+	// Users are encouraged to follow OCI image-spec https://github.com/opencontainers/image-spec/blob/main/annotations.md
+	Annotations map[string]string `json:"annotations,omitempty"`
 }
 
 // ZarfBuildData is written during the packager.Create() operation to track details of the created package.

src/internal/packager2/layout/oci.go

@@ -8,6 +8,7 @@ import (
 	"errors"
 	"fmt"
 	"log/slog"
+	"maps"
 	"strings"
 
 	"github.com/defenseunicorns/pkg/helpers/v2"
@@ -144,5 +145,7 @@ func annotationsFromMetadata(metadata v1alpha1.ZarfMetadata) map[string]string {
 	if vendor := metadata.Vendor; vendor != "" {
 		annotations[ocispec.AnnotationVendor] = vendor
 	}
+	// annotations explicitly defined in `metadata.annotations` take precedence over legacy fields
+	maps.Copy(annotations, metadata.Annotations)
 	return annotations
 }

src/internal/packager2/layout/oci_test.go

@@ -21,16 +21,21 @@ func TestAnnotationsFromMetadata(t *testing.T) {
 		Documentation: "documentation",
 		Source:        "source",
 		Vendor:        "vendor",
+		Annotations: map[string]string{
+			"org.opencontainers.image.title": "overridden",
+			"org.opencontainers.image.new":   "new-field",
+		},
 	}
 	annotations := annotationsFromMetadata(metadata)
 	expectedAnnotations := map[string]string{
-		"org.opencontainers.image.title":         "foo",
+		"org.opencontainers.image.title":         "overridden",
 		"org.opencontainers.image.description":   "bar",
 		"org.opencontainers.image.url":           "https://example.com",
 		"org.opencontainers.image.authors":       "Zarf",
 		"org.opencontainers.image.documentation": "documentation",
 		"org.opencontainers.image.source":        "source",
 		"org.opencontainers.image.vendor":        "vendor",
+		"org.opencontainers.image.new":           "new-field",
 	}
 	require.Equal(t, expectedAnnotations, annotations)
 }

src/pkg/zoci/push.go

@@ -8,6 +8,7 @@ import (
 	"context"
 	"errors"
 	"fmt"
+	"maps"
 
 	"github.com/defenseunicorns/pkg/helpers/v2"
 	"github.com/defenseunicorns/pkg/oci"
@@ -116,6 +117,7 @@ func annotationsFromMetadata(metadata *v1alpha1.ZarfMetadata) map[string]string
 	if vendor := metadata.Vendor; vendor != "" {
 		annotations[ocispec.AnnotationVendor] = vendor
 	}
-
+	// annotations explicitly defined in `metadata.annotations` take precedence over legacy fields
+	maps.Copy(annotations, metadata.Annotations)
 	return annotations
 }

zarf.schema.json

@@ -1076,6 +1076,13 @@
         "aggregateChecksum": {
           "type": "string",
           "description": "Checksum of a checksums.txt file that contains checksums all the layers within the package."
+        },
+        "annotations": {
+          "additionalProperties": {
+            "type": "string"
+          },
+          "type": "object",
+          "description": "Annotations contains arbitrary metadata about the package.\nUsers are encouraged to follow OCI image-spec https://github.com/opencontainers/image-spec/blob/main/annotations.md"
         }
       },
       "additionalProperties": false,