feat(values)!: support schema merge on imports (#4951)

Signed-off-by: Brandt Keller <brandt.keller@defenseunicorns.com>

Author: brandtkeller

src/cmd/dev.go

@@ -133,12 +133,12 @@ func (o *devInspectDefinitionOptions) run(cmd *cobra.Command, args []string) err
 	if err != nil {
 		return err
 	}
-	pkg, err := load.PackageDefinition(ctx, basePath, loadOpts)
+	defined, err := load.PackageDefinition(ctx, basePath, loadOpts)
 	if err != nil {
 		return err
 	}
-	pkg.Build = v1alpha1.ZarfBuildData{}
-	err = utils.ColorPrintYAML(pkg, nil, false)
+	defined.Pkg.Build = v1alpha1.ZarfBuildData{}
+	err = utils.ColorPrintYAML(defined.Pkg, nil, false)
 	if err != nil {
 		return err
 	}

src/pkg/packager/create.go

@@ -63,7 +63,7 @@ func Create(ctx context.Context, packagePath string, output string, opts CreateO
 		SkipVersionCheck:   opts.SkipVersionCheck,
 		RemoteOptions:      opts.RemoteOptions,
 	}
-	pkg, err := load.PackageDefinition(ctx, packagePath, loadOpts)
+	defined, err := load.PackageDefinition(ctx, packagePath, loadOpts)
 	if err != nil {
 		return "", err
 	}
@@ -76,7 +76,7 @@ func Create(ctx context.Context, packagePath string, output string, opts CreateO
 	var differentialPkg v1alpha1.ZarfPackage
 	if opts.DifferentialPackagePath != "" {
 		pkgLayout, err := LoadPackage(ctx, opts.DifferentialPackagePath, LoadOptions{
-			Architecture:   pkg.Metadata.Architecture,
+			Architecture:   defined.Pkg.Metadata.Architecture,
 			RemoteOptions:  opts.RemoteOptions,
 			LayerTypes:     []zoci.LayerType{zoci.MetadataLayers},
 			OCIConcurrency: opts.OCIConcurrency,
@@ -103,7 +103,7 @@ func Create(ctx context.Context, packagePath string, output string, opts CreateO
 		WithBuildMachineInfo: opts.WithBuildMachineInfo,
 		RemoteOptions:        opts.RemoteOptions,
 	}
-	pkgLayout, err := layout.AssemblePackage(ctx, pkg, pkgPath.BaseDir, assembleOpt)
+	pkgLayout, err := layout.AssemblePackage(ctx, defined.Pkg, pkgPath.BaseDir, defined.ImportedSchemas, assembleOpt)
 	if err != nil {
 		return "", err
 	}

src/pkg/packager/deploy.go

@@ -169,7 +169,7 @@ func Deploy(ctx context.Context, pkgLayout *layout.PackageLayout, opts DeployOpt
 	vals.DeepMerge(opts.Values)
 
 	// Validate merged values against schema if provided
-	if pkgLayout.Pkg.Values.Schema != "" {
+	if pkgLayout.HasValuesSchema() {
 		schemaPath := filepath.Join(pkgLayout.DirPath(), layout.ValuesSchema)
 		if err := vals.Validate(ctx, schemaPath, value.ValidateOptions{}); err != nil {
 			return DeployResult{}, fmt.Errorf("values validation failed: %w", err)

src/pkg/packager/dev.go

@@ -78,7 +78,7 @@ func DevDeploy(ctx context.Context, packagePath string, opts DevDeployOptions) (
 		SkipVersionCheck: opts.SkipVersionCheck,
 		RemoteOptions:    opts.RemoteOptions,
 	}
-	pkg, err := load.PackageDefinition(ctx, packagePath, loadOpts)
+	defined, err := load.PackageDefinition(ctx, packagePath, loadOpts)
 	if err != nil {
 		return err
 	}
@@ -87,17 +87,17 @@ func DevDeploy(ctx context.Context, packagePath string, opts DevDeployOptions) (
 		filters.ByLocalOS(runtime.GOOS),
 		filters.ForDeploy(opts.OptionalComponents, false),
 	)
-	pkg.Components, err = filter.Apply(pkg)
+	defined.Pkg.Components, err = filter.Apply(defined.Pkg)
 	if err != nil {
 		return err
 	}
 
 	// If not building for airgap, strip out all images and repos
 	if !opts.AirgapMode {
-		for idx := range pkg.Components {
-			pkg.Components[idx].Images = []string{}
-			pkg.Components[idx].ImageArchives = []v1alpha1.ImageArchive{}
-			pkg.Components[idx].Repos = []string{}
+		for idx := range defined.Pkg.Components {
+			defined.Pkg.Components[idx].Images = []string{}
+			defined.Pkg.Components[idx].ImageArchives = []v1alpha1.ImageArchive{}
+			defined.Pkg.Components[idx].Repos = []string{}
 		}
 	}
 
@@ -108,7 +108,7 @@ func DevDeploy(ctx context.Context, packagePath string, opts DevDeployOptions) (
 		OCIConcurrency:    opts.OCIConcurrency,
 		CachePath:         opts.CachePath,
 	}
-	pkgLayout, err := layout.AssemblePackage(ctx, pkg, packagePath, createOpts)
+	pkgLayout, err := layout.AssemblePackage(ctx, defined.Pkg, packagePath, defined.ImportedSchemas, createOpts)
 	if err != nil {
 		return err
 	}

src/pkg/packager/find_images.go

@@ -108,16 +108,16 @@ func FindDefinitionImages(ctx context.Context, packagePath string, opts FindImag
 		SkipVersionCheck: true,
 		RemoteOptions:    opts.RemoteOptions,
 	}
-	pkg, err := load.PackageDefinition(ctx, packagePath, loadOpts)
+	defined, err := load.PackageDefinition(ctx, packagePath, loadOpts)
 	if err != nil {
 		return nil, err
 	}
-	imageScans, err := findImages(ctx, pkg, packagePath, opts)
+	imageScans, err := findImages(ctx, defined.Pkg, packagePath, opts)
 	if err != nil {
 		return nil, err
 	}
 
-	return filterImagesFoundInArchives(ctx, pkg, packagePath, imageScans)
+	return filterImagesFoundInArchives(ctx, defined.Pkg, packagePath, imageScans)
 }
 
 // FindImages iterates over the manifests and charts within each component to find any container images
@@ -136,12 +136,12 @@ func FindImages(ctx context.Context, packagePath string, opts FindImagesOptions)
 		SkipVersionCheck: true,
 		RemoteOptions:    opts.RemoteOptions,
 	}
-	pkg, err := load.PackageDefinition(ctx, packagePath, loadOpts)
+	defined, err := load.PackageDefinition(ctx, packagePath, loadOpts)
 	if err != nil {
 		return nil, err
 	}
 
-	return findImages(ctx, pkg, packagePath, opts)
+	return findImages(ctx, defined.Pkg, packagePath, opts)
 }
 
 // filterImagesFoundInArchives merges scan results with each component's imageArchives.

src/pkg/packager/inspect.go

@@ -79,7 +79,7 @@ func InspectPackageResources(ctx context.Context, pkgLayout *layout.PackageLayou
 	}
 	vals.DeepMerge(opts.Values)
 
-	if pkgLayout.Pkg.Values.Schema != "" {
+	if pkgLayout.HasValuesSchema() {
 		schemaPath := filepath.Join(pkgLayout.DirPath(), layout.ValuesSchema)
 		if err := vals.Validate(ctx, schemaPath, value.ValidateOptions{SkipRequired: true}); err != nil {
 			return nil, fmt.Errorf("inspect values validation failed: %w", err)
@@ -246,10 +246,11 @@ func InspectDefinitionResources(ctx context.Context, packagePath string, opts In
 		SkipVersionCheck: true,
 		RemoteOptions:    opts.RemoteOptions,
 	}
-	pkg, err := load.PackageDefinition(ctx, packagePath, loadOpts)
+	defined, err := load.PackageDefinition(ctx, packagePath, loadOpts)
 	if err != nil {
 		return nil, err
 	}
+	pkg := defined.Pkg
 	variableConfig, err := getPopulatedVariableConfig(ctx, pkg, opts.DeploySetVariables, opts.IsInteractive)
 	if err != nil {
 		return nil, err

src/pkg/packager/layout/assemble.go

@@ -62,7 +62,7 @@ type AssembleOptions struct {
 }
 
 // AssemblePackage takes a package definition and returns a package layout with all the resources collected
-func AssemblePackage(ctx context.Context, pkg v1alpha1.ZarfPackage, packagePath string, opts AssembleOptions) (*PackageLayout, error) {
+func AssemblePackage(ctx context.Context, pkg v1alpha1.ZarfPackage, packagePath string, importedSchemas []string, opts AssembleOptions) (*PackageLayout, error) {
 	l := logger.From(ctx)
 	l.Info("assembling package", "path", packagePath)
 
@@ -180,11 +180,8 @@ func AssemblePackage(ctx context.Context, pkg v1alpha1.ZarfPackage, packagePath
 		return nil, err
 	}
 
-	// Copy schema file if specified
-	if pkg.Values.Schema != "" {
-		if err = copyValuesSchema(ctx, pkg.Values.Schema, packagePath, buildPath); err != nil {
-			return nil, err
-		}
+	if err = mergeAndWriteValuesSchema(ctx, pkg.Values.Schema, importedSchemas, packagePath, buildPath); err != nil {
+		return nil, err
 	}
 
 	if err = createDocumentationTar(pkg, packagePath, buildPath); err != nil {
@@ -244,11 +241,11 @@ type AssembleSkeletonOptions struct {
 }
 
 // AssembleSkeleton creates a skeleton package and returns the path to the created package.
-func AssembleSkeleton(ctx context.Context, pkg v1alpha1.ZarfPackage, packagePath string, opts AssembleSkeletonOptions) (*PackageLayout, error) {
+func AssembleSkeleton(ctx context.Context, pkg v1alpha1.ZarfPackage, packagePath string, importedSchemas []string, opts AssembleSkeletonOptions) (*PackageLayout, error) {
 	pkg.Metadata.Architecture = v1alpha1.SkeletonArch
 
-	// Creating skeletons packages with the values feature is not yet supported
-	if len(pkg.Values.Files) > 0 || pkg.Values.Schema != "" {
+	// Creating skeleton packages with the values feature is not yet supported
+	if len(pkg.Values.Files) > 0 || pkg.Values.Schema != "" || len(importedSchemas) > 0 {
 		return nil, errors.New("creating skeleton packages with the values feature is not yet supported")
 	}
 
@@ -1031,36 +1028,131 @@ func mergeAndWriteValuesFile(ctx context.Context, files []string, packagePath, b
 	return nil
 }
 
-// copyValuesSchema validates and copies a values schema file to the build directory.
-// It validates the schema is valid JSON Schema, checks for path traversal, and copies
-// the file to the package root.
-func copyValuesSchema(ctx context.Context, schema, packagePath, buildPath string) error {
+// mergeAndWriteValuesSchema merges imported child schemas with the parent schema (parent wins)
+// and writes the result to buildPath/values.schema.json. If only a parent schema exists with
+// no imports, it is validated and copied as-is. If only child schemas exist, they are merged
+// and written. If neither exists, the function is a no-op.
+//
+// Schemas containing "$ref" pointers are rejected in all cases because references may point
+// to files unavailable after assembly.
+func mergeAndWriteValuesSchema(ctx context.Context, parentSchema string, importedSchemas []string, packagePath, buildPath string) error {
 	l := logger.From(ctx)
-	l.Debug("copying values schema file to package", "schema", schema)
 
-	// Resolve the schema source path from package root
-	schemaSrc := schema
-	if !filepath.IsAbs(schemaSrc) {
-		schemaSrc = filepath.Join(packagePath, schema)
+	if parentSchema == "" && len(importedSchemas) == 0 {
+		return nil
+	}
+
+	// loadSchema reads a schema file, rejects any external "$ref" pointers before handing
+	// the document to gojsonschema, then validates the schema structure. CheckNoExternalRefs
+	// runs first so that gojsonschema never attempts to resolve external URIs.
+	loadSchema := func(relPath, label string) (map[string]any, error) {
+		src := relPath
+		if !filepath.IsAbs(src) {
+			src = filepath.Join(packagePath, relPath)
+		}
+		b, err := os.ReadFile(src)
+		if err != nil {
+			return nil, fmt.Errorf("reading %s schema: %w", label, err)
+		}
+		var s map[string]any
+		if err := json.Unmarshal(b, &s); err != nil {
+			return nil, fmt.Errorf("parsing %s schema: %w", label, err)
+		}
+		if err := value.CheckNoExternalRefs(s); err != nil {
+			return nil, fmt.Errorf("%s schema %s: %w", label, relPath, err)
+		}
+		if err := value.ValidateSchemaDocument(s); err != nil {
+			return nil, fmt.Errorf("%s schema validation failed: %w", label, err)
+		}
+		return s, nil
+	}
+
+	// No child schemas — check for $ref, validate, then copy the parent schema file verbatim.
+	if len(importedSchemas) == 0 {
+		src := parentSchema
+		if !filepath.IsAbs(src) {
+			src = filepath.Join(packagePath, parentSchema)
+		}
+		if _, err := loadSchema(parentSchema, "parent"); err != nil {
+			return err
+		}
+		dst := filepath.Join(buildPath, ValuesSchema)
+		l.Debug("copying values schema file", "src", src, "dst", dst)
+		if err := helpers.CreatePathAndCopy(src, dst); err != nil {
+			return fmt.Errorf("failed to copy values schema file %s: %w", parentSchema, err)
+		}
+		return os.Chmod(dst, helpers.ReadWriteUser)
+	}
+
+	l.Debug("merging values schemas", "parent", parentSchema, "imported", len(importedSchemas))
+
+	// Merge child schemas left-to-right; among children the earlier one wins.
+	var merged map[string]any
+	for _, schemaRelPath := range importedSchemas {
+		child, err := loadSchema(schemaRelPath, "imported")
+		if err != nil {
+			return err
+		}
+		if schemaVersion(child) == "" {
+			return fmt.Errorf("imported schema %s: missing \"$schema\" version declaration; all schemas being merged must specify a version", schemaRelPath)
+		}
+		if merged == nil {
+			merged = child
+		} else {
+			if err := checkCompatibleVersion(merged, child, schemaRelPath); err != nil {
+				return err
+			}
+			merged = value.MergeSchemas(merged, child)
+		}
 	}
 
-	// Validate the schema is valid JSON Schema
-	if err := value.ValidateSchemaFile(schemaSrc); err != nil {
-		return fmt.Errorf("values schema validation failed: %w", err)
+	// Load the parent schema and merge it on top — parent wins over all children.
+	if parentSchema != "" {
+		parent, err := loadSchema(parentSchema, "parent")
+		if err != nil {
+			return err
+		}
+		if schemaVersion(parent) == "" {
+			return fmt.Errorf("parent schema %s: missing \"$schema\" version declaration; all schemas being merged must specify a version", parentSchema)
+		}
+		if err := checkCompatibleVersion(parent, merged, "imported schemas"); err != nil {
+			return err
+		}
+		merged = value.MergeSchemas(parent, merged)
 	}
 
-	// Copy schema file to package root
-	schemaDst := filepath.Join(buildPath, ValuesSchema)
-	l.Debug("copying values schema file", "src", schemaSrc, "dst", schemaDst)
-	if err := helpers.CreatePathAndCopy(schemaSrc, schemaDst); err != nil {
-		return fmt.Errorf("failed to copy values schema file %s: %w", schemaSrc, err)
+	if err := value.ValidateSchemaDocument(merged); err != nil {
+		return fmt.Errorf("merged values schema is invalid: %w", err)
 	}
 
-	// Set appropriate file permissions
-	if err := os.Chmod(schemaDst, helpers.ReadWriteUser); err != nil {
-		return fmt.Errorf("failed to set permissions on values schema file %s: %w", schemaDst, err)
+	dst := filepath.Join(buildPath, ValuesSchema)
+	l.Debug("writing merged values schema", "dst", dst)
+	b, err := json.MarshalIndent(merged, "", "  ")
+	if err != nil {
+		return fmt.Errorf("failed to marshal merged values schema: %w", err)
+	}
+	if err := os.WriteFile(dst, b, helpers.ReadWriteUser); err != nil {
+		return fmt.Errorf("failed to write merged values schema: %w", err)
 	}
+	return nil
+}
 
+// schemaVersion extracts the "$schema" version URI from a schema map, returning "" if absent or not a string.
+func schemaVersion(s map[string]any) string {
+	if v, ok := s["$schema"].(string); ok {
+		return v
+	}
+	return ""
+}
+
+// checkCompatibleVersion errors when the accumulated merged schema and an incoming schema declare
+// different "$schema" versions, preventing silent cross-version merge bugs.
+func checkCompatibleVersion(accumulated, incoming map[string]any, incomingLabel string) error {
+	a := schemaVersion(accumulated)
+	b := schemaVersion(incoming)
+	if a != b {
+		return fmt.Errorf("cannot merge schemas with different versions: accumulated schema uses %q but %s declares %q", a, incomingLabel, b)
+	}
 	return nil
 }