ZEP-0051: v1beta1 schema

0048-schema-update-process/README.md

@@ -186,7 +186,7 @@ As a package creator, I want to create and publish packages using the newer API
 
 #### Story 3
 
-As a package creator, I want to update my package definition to the v1beta1 schema, so I run `zarf dev upgrade-schema --to v1beta1` with a zarf.yaml in my current directory and it outputs the converted package definition to stdout.
+As a package creator, I want to update my package definition to the v1beta1 schema, so I run `zarf dev upgrade-schema . --to v1beta1 > zarf.yaml` against the directory containing my zarf.yaml. The command writes the converted definition to stdout, replacing my existing zarf.yaml.
 
 #### Story 4
 
@@ -472,6 +472,10 @@ not need to be as detailed as the proposal, but should include enough
 information to express the idea and why it was not acceptable.
 -->
 
+### Use only one API version
+
+Instead of introducing a new schema, we could over time remove and introduce fields on the existing package schema. This was rejected as we believe a new schema will provide a more intuitive experience for developers and maintainers. For instance, attempting to implement the proposed Helm changes would result in a large, confusing schema. Likewise, it would be difficult to change defaults, such as moving from required to optional, since we wouldn't have a new API version to signal that there is a breaking change. Additionally, removing deprecated fields such as `dataInjections` would require a major version change. Keeping the API version and CLI version decoupled allows flexibility to make the changes we need.
+
 ### Public Facing Internal Type
 
 Rather than updating functions to accept a newer version of the schema, Zarf could have a publicly facing internal type that has every field from every version and use that throughout the SDK. The upside of this approach is that we would avoid breaking changes throughout the lifetime of the SDK. The downside is that it would make it easy for anyone using the SDK to set deprecated fields. It would also make it confusing and unclear which fields attach to which versions. 

0048-schema-update-process/zep.yaml

@@ -12,19 +12,17 @@ approvers:
   - "@zarf-dev"
 
 see-also:
-  # Will add the v1 schema here when applicable
+  - "/0051-v1beta1-schema"
 replaces:
 
 # The target maturity stage in the current dev cycle for this ZEP.
-stage: alpha
+stage: ""
 
 # The most recent milestone for which work toward delivery of this ZEP has been
 # done. This can be the current (upcoming) milestone, if it is being actively
 # worked on.
-latest-milestone: "v0.65.0"
+latest-milestone: "v0.75.0"
 
 # The milestone at which this feature was, or is targeted to be, at each stage.
 milestone:
-  alpha: "v0.65.0"
-  beta: "v0.65.0"
-  stable: "v0.65.0"
+  stable: "TBD"

0051-v1beta1-schema/componentConfig.go

@@ -0,0 +1,66 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2021-Present The Zarf Authors
+
+package v1beta1
+
+// ComponentConfig is the top-level structure of a Zarf component config file.
+type ComponentConfig struct {
+	// The API version of the component config.
+	APIVersion string `json:"apiVersion" jsonschema:"enum=zarf.dev/v1beta1"`
+	// The kind of component config.
+	Kind PackageKind `json:"kind" jsonschema:"enum=ZarfComponentConfig,default=ZarfComponentConfig"`
+	// Component metadata.
+	Metadata ComponentMetadata `json:"metadata"`
+	// The single component this config defines.
+	Component Component `json:"component"`
+	// Values imports Zarf values files for templating and overriding Helm values.
+	Values Values `json:"values,omitempty"`
+	// Zarf-generated publish data for the component config.
+	PublishData ComponentPublishData `json:"publishData,omitempty"`
+}
+
+// ImportableComponent is a reduced component definition used in component configs.
+type ImportableComponent struct {
+	// Import a component from another Zarf component config.
+	Import ComponentImport `json:"import,omitempty"`
+	// Filter when this component is included in package creation or deployment.
+	Target ComponentTarget `json:"target,omitempty"`
+	// Kubernetes manifests to be included in a generated Helm chart on package deploy.
+	Manifests []Manifest `json:"manifests,omitempty"`
+	// Helm charts to install during package deploy.
+	Charts []Chart `json:"charts,omitempty"`
+	// Files or folders to place on disk during package deployment.
+	Files []File `json:"files,omitempty"`
+	// List of OCI images to include in the package.
+	Images []Image `json:"images,omitempty"`
+	// List of tar archives of images to include in the package.
+	ImageArchives []ImageArchive `json:"imageArchives,omitempty"`
+	// List of git repositories to include in the package.
+	Repositories []string `json:"repositories,omitempty"`
+	// Custom commands to run at various stages of a package lifecycle.
+	Actions ComponentActions `json:"actions,omitempty"`
+	// The Zarf CLI service this component provides, such as the registry, injector, or agent.
+	Service Service `json:"service,omitempty" jsonschema:"enum=registry,enum=seed-registry,enum=injector,enum=agent,enum=git-server"`
+}
+
+// ComponentMetadata holds metadata about a component config.
+type ComponentMetadata struct {
+	// Name to identify this component config.
+	Name string `json:"name" jsonschema:"pattern=^[a-z0-9][a-z0-9\\-]*$"`
+	// Additional information about this component config.
+	Description string `json:"description,omitempty"`
+	// Generic string to track the component config version.
+	Version string `json:"version,omitempty"`
+	// Annotations contains arbitrary metadata about the component config.
+	Annotations map[string]string `json:"annotations,omitempty"`
+}
+
+// ComponentPublishData is written during publish to track details of the component config.
+type ComponentPublishData struct {
+	// The version of Zarf used to build this component config.
+	ZarfVersion string `json:"zarfVersion"`
+	// Any migrations that have been run on this component config.
+	Migrations []string `json:"migrations,omitempty"`
+	// Requirements for specific package operations.
+	VersionRequirements []VersionRequirement `json:"versionRequirements,omitempty"`
+}