[Bug]: topologySpreadConstraints JSON schema is invalid with helm v3.18.5+

[Moglum]

Version

4.0.1

What Kubernetes platforms are you running on?

EKS Amazon

Steps to reproduce

Helm v3.18.5 changed the Go library for validating JSON Schema https://github.com/helm/helm/releases/tag/v3.18.5
helm/helm@cb8595b

which uncovered a problem with the nginx-ingress topologySpreadConstraints JSON schema in the Helm chart.

The problem is that the JSON schema incorrectly specifies controller.topologySpreadConstraints as object https://github.com/nginx/kubernetes-ingress/blob/main/charts/nginx-ingress/values.schema.json#L919
but the referenced schema https://raw.githubusercontent.com/nginxinc/kubernetes-json-schema/master/v1.33.1/_definitions.json#/definitions/io.k8s.api.core.v1.PodSpec/properties/topologySpreadConstraints
specifies it (correctly) as "array"

How to reproduce

• Prepare values-array.yaml

controller:
  topologySpreadConstraints:
    - maxSkew: 1
      topologyKey: "topology.kubernetes.io/zone"
      whenUnsatisfiable: ScheduleAnyway
      labelSelector:
        matchLabels:
          helmapp.kubernetes.io/name: nginx-ingress

• connect Helm repo

helm repo add nginx https://helm.nginx.com/stable

• run local templating with Helm

❯ helm version
version.BuildInfo{Version:"v3.18.6", GitCommit:"b76a950f6835474e0906b96c9ec68a2eff3a6430", GitTreeState:"clean", GoVersion:"go1.25.0"}
❯ helm template nginx nginx/nginx-ingress -f values-array.yaml
Error: values don't meet the specifications of the schema(s) in the following chart(s):
nginx-ingress:
- at '/controller/topologySpreadConstraints': got array, want object

when JSON schema validation is disabled, it produces valid manifest

❯ helm template nginx nginx/nginx-ingress -f values-array.yaml --skip-schema-validation | kubeconform -strict -verbose
stdin - ConfigMap nginx-nginx-ingress-leader-election is valid
stdin - ServiceAccount nginx-nginx-ingress is valid
stdin - ConfigMap nginx-nginx-ingress is valid
stdin - ClusterRole nginx-nginx-ingress is valid
stdin - Role nginx-nginx-ingress is valid
stdin - RoleBinding nginx-nginx-ingress is valid
stdin - ClusterRoleBinding nginx-nginx-ingress is valid
stdin - Service nginx-nginx-ingress-controller is valid
stdin - IngressClass nginx is valid
stdin - Deployment nginx-nginx-ingress-controller is valid
stdin - Lease nginx-nginx-ingress-leader-election is valid

With older version of Helm this works just fine

❯ ~/tmp/helm-old version
version.BuildInfo{Version:"v3.18.4", GitCommit:"d80839cf37d860c8aa9a0503fe463278f26cd5e2", GitTreeState:"clean", GoVersion:"go1.24.4"}
❯ ~/tmp/helm-old template nginx nginx/nginx-ingress -f values-array.yaml
---
# Source: nginx-ingress/templates/controller-serviceaccount.yaml
apiVersion: v1
kind: ServiceAccount
metadata:
  name: nginx-nginx-ingress
  namespace: default
  labels:
    helm.sh/chart: nginx-ingress-2.2.2
    app.kubernetes.io/name: nginx-ingress
    app.kubernetes.io/instance: nginx
    app.kubernetes.io/version: "5.1.1"
    app.kubernetes.io/managed-by: Helm
...

[github-actions]

Hi @Moglum thanks for reporting!

Be sure to check out the docs and the Contributing Guidelines while you wait for a human to take a look at this 🙂

Cheers!

[javorszky]

Hey @Moglum ,

We're going to look at it. There are a number of different approaches we can take, and a ton of consideration needs to go into how we fix this to not break this for folks on helm 3.18.4 or earlier. Please bear with us for a little bit.

[Moglum]

It should be pretty straightforward. The type parameter for any node in the values.schema.json that uses a $ref is redundant anyway. The type and any other details are taken only from the referenced schema.

In the case of controller.topologySpreadConstraints simply removing the "type": "object", line solves the problem for both older and new versions of Helm. topologySpreadConstraints can't be an object, as that would produce an invalid K8s manifest. And the referenced schema correctly specifies it as an array.

[Anil-YadavK8s]

Facing same issue with helm chart version: 2.2.2

**error: Error: values don't meet the specifications of the schema(s) in the following chart(s): nginx-ingress: - at '/controller/topologySpreadConstraints': got object, want array : unable to run: 'helm template nginx-ingress**

====Values.yaml snippet===
`**controller:
topologySpreadConstraints:

• maxSkew: 1
  topologyKey: kubernetes.io/hostname
  whenUnsatisfiable: DoNotSchedule
  labelSelector:
  matchLabels:
  app.kubernetes.io/name: nginx-ingress
  matchLabelKeys:
  • pod-template-hash**`

It seems like a mismatch between values.schema.json of chart , where is expect a "type: object" but in ref (i guess it is k8s api)it is an "array"

----chart's values.schema.json----
"topologySpreadConstraints": { "type": "object", "default": {}, "title": "The topologySpreadConstraints Schema", "$ref": "https://raw.githubusercontent.com/nginxinc/kubernetes-json-schema/master/v1.33.1/_definitions.json#/definitions/io.k8s.api.core.v1.PodSpec/properties/topologySpreadConstraints" },

[haywoodsh]

Validation still fails as of helm 3.19

Relevant issue on Helm repo: helm/helm#31148

Future Helm schema validation:

As per spec if $ref present then all its siblings must be ignored

santhosh-tekuri/jsonschema#221 (comment)