From 7af3336b01eddeffd2c9cd165854196f221bb9b0 Mon Sep 17 00:00:00 2001
From: Austin Abro <37223396+AustinAbro321@users.noreply.github.com>
Date: Thu, 12 Dec 2024 14:32:28 -0500
Subject: [PATCH] feat: add metadata.annotations to package schema (#3319)

Signed-off-by: Austin Abro <AustinAbro321@gmail.com>
---
 src/api/v1alpha1/package.go               | 3 +++
 src/internal/packager2/layout/oci.go      | 3 +++
 src/internal/packager2/layout/oci_test.go | 7 ++++++-
 src/pkg/zoci/push.go                      | 4 +++-
 zarf.schema.json                          | 7 +++++++
 5 files changed, 22 insertions(+), 2 deletions(-)

diff --git a/src/api/v1alpha1/package.go b/src/api/v1alpha1/package.go
index 2ae9734ac6..db4c95ff59 100644
--- a/src/api/v1alpha1/package.go
+++ b/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.
diff --git a/src/internal/packager2/layout/oci.go b/src/internal/packager2/layout/oci.go
index 6ee23f43b7..b1c21bd5b3 100644
--- a/src/internal/packager2/layout/oci.go
+++ b/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
 }
diff --git a/src/internal/packager2/layout/oci_test.go b/src/internal/packager2/layout/oci_test.go
index 53341047f1..3904729be3 100644
--- a/src/internal/packager2/layout/oci_test.go
+++ b/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)
 }
diff --git a/src/pkg/zoci/push.go b/src/pkg/zoci/push.go
index 5727849ae2..e0a6b5c782 100644
--- a/src/pkg/zoci/push.go
+++ b/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
 }
diff --git a/zarf.schema.json b/zarf.schema.json
index 9b474b9400..b54837d605 100644
--- a/zarf.schema.json
+++ b/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,