Add values.schema.json to the best practices

[mik-laj]

Hello,

I think it is worth adding to good practice creating values.schema.json file. This file allows us to validate the values.yaml file structure.

This may also be a good way to create documentation in the future. https://github.com/helm/helm/issues/8920

Related page: https://helm.sh/docs/chart_best_practices/values/

Best regards, Kamil Breguła

[kaxil]

Agreed, this would be a good addition

[alexrashed]

I also agree that this would be a nice addition. In fact, it would be nice if the docs would contain some best practices for the values.schema.json itself. For example:

• Do not use additionalProperties: false on global values. (Since the validation would fail if other global values are set for different a different chart)
• The default value should only be used with actually usable values. They should not contain any explanations about dynamically generated default values within the templates. (Since this would break the spec and limits the usability in other tools like form generators)

Here are some other questions I have (but couldn't find / derive a best practice yet):

• Which fields should be set as required?
  • All fields which are used with the required template function? (The values.schema.json does not tell which fields you actually have to set manually.
  • Only those fields which are used with the required template function but don't have a default set in the Chart's values.yaml? The static validation of a values.yaml cannot detect required fields which have been explicitly unset in a user's values.yaml`.
• Empty strings
  • Should the values.yaml have fields which are not set, or should unset fields be avoided (by setting an empty string)?
    When setting empty strings, the validation would be successful even though the field is not considered being set in the template functions (since an empty string is considered not set / false in the conditionals).
    When the field is not set at all in the values.yaml, the validation fails on the Chart itself. I guess this would be okay if it is a value which does not have a default and is required (i.e. it has to be set by a user of the chart).

Are there any opinions on those questions? Are there already some best practices about the usage of the values.schema.json out there in the wild?

For the sake of the discussion, here are the values.schema.json files in the (deprecated) helm/charts repo: https://github.com/helm/charts/search?q=filename%3A%22values.schema.json%22

[reitzig]

My personal take on this:

Which fields should be set as required?

As far as I can determine, helm validates the merged values (values.yaml + -f + --set) against the JSON Schema. As such, I believe the correct answer is your first option. However, this has "ugly" consequences for tooling: worst case, IDEA (for instance) won't show either of values.yaml or -f-injected files as valid.

Empty strings

Ran into this as well. Unset values work, but JSON Schema (and/or the validator used in helm) handles "unset" and "set to null" differently w.r.t. required. Also, we can't use null in all places, because helm doesn't honor "type" = ["string", "null"], unfortunately. My workaround is to set the values in values.yaml but to an invalid value; for instance, value: "" and add "minLength" = 1 to the schema. This way, all required values appear in values.yaml but will cause validation to fail unless overridden (with something valid).