Schema for empty array/object

[fopina]

If I have something like this in my chart values.yaml:

# -- Expose service
externalIngressRoutes: []
  # Example:
  #  - name: whatever
  #    other_name: whatever

How do I refactor it so this project picks up types (and @schema annotations) for the elements of the array?

Or should I create a separate values-examples.yaml in my chart that won't be used as default values but can be consumed by helm schema command?

[losisin]

You can use line comment like this:

# -- Expose service
externalIngressRoutes: [] # @schema item: string
  # Example:
  #  - name: whatever
  #    other_name: whatever

and that will generate json schema like this:

{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
        "externalIngressRoutes": {
            "type": "array",
            "items": {
                "type": "string"
            }
        }
    }
}

[losisin]

from the docs: https://github.com/losisin/helm-values-schema-json/blob/main/docs/README.md#item

[fopina]

Hi @losisin thanks for the quick feedback!

I probably mis-explained: I did go through readme and line @schema annotations but what I meant there is that I'd like to be able for the output schema to include the items of this array which are not string, they're objects themselves.

Meaning, if I have this (which is what I currently use in a separate values-examples.yaml also consumed by helm schema ...)

externalIngressRoutes:
 - name: whatever
    other_name: whatever

the output schema is

"externalIngressRoutes": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "name": {
                        "type": "string"
                    },
                    "other_name": {
                        "type": "string"
...

What I was wondering is if there's a way to "document" the "item" schema in values.yaml without actually defining a value: get this same schema generated but out of commented out example only

Just to note that I'm happy with my current workaround (values in values-example.yaml are used for schema but never as default values by helms using the chart), however I'd be happy to use the "right/clean way" if there is some

Thanks

[losisin]

That scenario is not supported

[fopina]

Clear, thanks for taking the time to understand the issue

For closure, in case anyone bumps into this, my current workaround is:

values.yaml

# -- Expose service
externalIngressRoutes: []
  # Example:
  #  - name: whatever
  #    other_name: whatever

values-examples.yaml

externalIngressRoutes:
  - name: whatever
    other_name: whatever

And generate schema with helm schema --use-helm-docs -f values.yaml -f values-examples.yaml

Only values.yaml is used as default values for helmfiles using the chart but schema is also inferred from the examples yaml

Cheers

[applejag]

It could be an interesting feature request to allow something like:

# (SYNTAX SUGGESTION IS NOT FINAL)

# -- Expose service
externalIngressRoutes: []

externalIngressRoutes#schema:
  - name: foo
    other_name: bar

What I'm saying is that if helm schema would have a feature to allow defining field schemas embedded in the same file without actually setting any default values, then I would personally not like it to be relying on writing the full structure in YAML comments. Instead it should be using normal YAML syntax so that tools like Yamllint can still help verify it.

The tricky part though is that the above would collide with whenever you use additionalProperties: false. And instead helm schema would need to try to add in a bunch of "patternProperties": { ".*#schema": {} }, everywhere in the output schema.

Doable, but not very fancy.

[fopina]

I like the idea of keeping yaml validation active (I've been uncommenting/re-commenting examples every time we want to make a change).
However, my impression (new to most of this, including k8s and helm) is that is more or less standard pattern to document examples. That would mean we'd have to document it in comments and again as a #schema?

Or maybe it could be externalIngressRoutes#example and actually be merged into externalIngressRoutes documentation as well, on top of schema inference?

[applejag]

However, my impression (new to most of this, including k8s and helm) is that is more or less standard pattern to document examples. That would mean we'd have to document it in comments and again as a #schema?

No it would be instead of comments.

Idea is that this:

foo: []
foo#schema: [{bar: true}]

becomes this:

"patternProperties": { ".*#schema": {} },
"properties": {
  "foo": {
    "type": "array",
    "items": {
      "type": "object",
      "properties": {
        "bar": {
          "type": "boolean"
        }
      }
    }
  }
}

If this is something we'd like to pursue then we can reopen this issue and have it as a feature request.

We'd still need to spend some more time designing it. I'm not overly fond of the #schema or #example suffix syntax. I don't find it "glance-able" enough, and could be too easily mistaken for a field by that name. It's not self-explanatory enough

[applejag]

You know, I like this idea. Let's reopen it and keep brainstorming

[applejag]

Other syntax ideas:

foo: []
foo (example): [{ bar: true }]

foo: []
foo / example: [{ bar: true }]

foo: []
foo | example: [{ bar: true }]

Multiple examples using optional number:

foo: []
foo (example 1): [{ bar: true }]
foo (example 2): [{ moo: 123 }]

foo: []
foo / example 1: [{ bar: true }]
foo / example 2: [{ moo: 123 }]

foo: []
foo | example 1: [{ bar: true }]
foo | example 2: [{ moo: 123 }]

resources: {}
resources (example):
  requests:
    # nested examples
    cpu (example 1): 100m
    cpu (example 2): 500m
    
    # should still be allowed to use "@schema" comments
    cpu (example 3): "2" # @schema type: [string, null]

    memory (example 1): 100M # @schema type: [string, null]
    memory (example 2): 100Mi
    memory (example 3): 2G
    memory (example 4): 2Gi

[applejag]

Should there perhaps also be a way to set the JSON Schema examples field via this?

For example:

imagePullSecrets: []
imagePullSecrets (example):
  - name: my-docker-credentials

"patternProperties": { ".* \\(example( \\d+)?\\)": {} }
"properties": {
  "imagePullSecrets": {
    "type": "array",
    "items": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        }
      }
    },
    "examples": [
      {
        "name": "my-docker-credentials"
      }
    ]
  }
}

Or should the examples only apply on scalar values?

"patternProperties": { ".* \\(example( \\d+)?\\)": {} }
"properties": {
  "imagePullSecrets": {
    "type": "array",
    "items": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "examples": [
            "my-docker-credentials"
          ]
        }
      }
    }
  }
}

[fopina]

I think using a separate file (as I am using now), covers most of this and avoids collisions or naming conventions (for exclusion)
However it misses actually being included as “example” in the schema and it is not so readable (as in different file)

However coming up with a convention such as those will actually set those properties/values in any helmfile - not that I see an issue but feels unintended

Maybe it could be something around/similar to $ref so it would be clear when reading the file that value type was defined somewhere else?