ZEP-0051: v1beta1 schema #52

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged

AustinAbro321 merged 138 commits into main from v1beta1-schema

Jun 1, 2026

0048-schema-update-process/README.md

            
                      Original file line number
                      Diff line number
                      Diff line change
                  
    @@ -156,7 +156,7 @@ All future package definition schemas will require a root level `apiVersion` fie
  
    During Zarf's lifetime, it will introduce, deprecate, and drop support for ZarfPackageConfig API versions. Once a version is deprecated, users will still be able to perform all package operations such as create, publish, and deploy, but will receive warnings that they should upgrade. Zarf will drop support for an API version one year after it is deprecated. Once an API version is no longer supported, Zarf will error if a user tries to perform common package operations with that API version such as `zarf package create`, `zarf package publish`, or `zarf package deploy`. Even after Zarf drops official support for an API version, Zarf will still work with the commands `zarf package inspect`, `zarf package remove`, and `zarf package pull` for an additional year. These commands will help users understand their unsupported existing packages, which may have already been deployed to a cluster, so that they can migrate them. The SDK will follow the same timeline, i.e. one year for `packager.Create`, two years for `packager.Pull`. 

    The zarf.yaml in a built package will include the package definition for every supported API version. When printing the package definition to the user, for example with the command `zarf package inspect definition`, the printed definition will be the latest API version by default. A new flag `--api-version` will be introduced to `zarf package inspect definition` and `zarf dev inspect definition` to allow configuring the output. 

    The zarf.yaml in a built package will include the package definition for every supported API version. When printing the package definition to the user, for example with the command `zarf package inspect definition`, the output will be the API version of the package by default. A new flag `--api-version` will be introduced to `zarf package inspect definition` and `zarf dev inspect definition` to allow configuring the output. 

    A new command `zarf dev upgrade-schema` will be introduced to allow users to convert from one API version to another. The command will default to converting to the latest API version. It will output the converted package definition for the latest schema version. It will accept a path to a directory containing a zarf.yaml file and an optional flag, `--to`, to declare the API version. For instance, a user could run `zarf dev upgrade-schema . --to v1beta1` and they will receive the converted package definition to stdout. The command will not allow changing from a newer version to an older version, so running `zarf dev upgrade-schema . --to=v1alpha1` on a `v1beta1` schema will error. This command will only accept a local package definition, and will not accept created packages, published packages, or deployed packages. 

    @@ -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

            
                      Original file line number
                      Diff line number
                      Diff line change
                  
    @@ -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"

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

ZEP-0051: v1beta1 schema #52

Uh oh!

Diff view

Diff view

There are no files selected for viewing

Uh oh!