Metadata improvements

[dud225]

Hello

readme-generator currently lacks some flexibility on what it generates.

There is no way to provide the users some leeway about the types that we accommodate. For example we may want to allow booleans and numbers to be expressed as strings: "true", "1":

    "boolean": {
      "id": "#boolean",
      "oneOf": [
        {
          "type": "boolean"
        },
        {
          "type": "string",
          "enum": [
            "true",
            "false"
          ]
        }
      ]
    },
    "string_or_integer": {
      "id": "#string_or_integer",
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "integer"
        }
      ]
    },

Also we may want to limit what fields a object can have:

      "required": [
        ....
      ],
      "additionalProperties": false

Maybe we could piggyback on the extra properties file discussed elsewhere: https://github.com/bitnami-labs/readme-generator-for-helm/issues/15

Regards.

[miguelaeh]

Hi @dud225 ,

About the types, could you elaborate on why it is needed? booleans and numbers are valid types following the OpenAPI v3 specification. Without the full context of why you need it, I think you can always process the JSON output to change those types to strings.

Also we may want to limit what fields a object can have

mm you want to limit what fields an object can have or specify what fields an object must have?

[dud225]

Hello.

readme-generator is able to generate a Helm values schema, what you call a metadata. In this metadata, the type of each Helm value is infered from the default values right? But some users may be used to express boolean or numeric values with strings, e.g.

enabled: "true"
replica: "2"

So in order to provide some flexibility, as a chart author I'm used to allow such usage by leverage a oneOf expression (cf my first message). Currently readme-generator doesn't offer this flexibility.

mm you want to limit what fields an object can have or specify what fields an object must have?

I would like to be able to enforce both, to force some mandatory values to be present and to catch non-existant fields (e.g. due to a typo).

[miguelaeh]

the type of each Helm value is infered from the default values right?

yes, if you change in the default value from a boolean true to a string "true", and re-generate the schema, it will change its type.

So, in short, what you are requesting is to support a parameter to be provided in different types, for example string and boolean, that will be represented in the schema by an anyOf. I think that in order to support that, we could apply the modifiers in a better way, instead of just adding one, we could use them for the supported types separated by commas and use the first one as the actual value for the parameter (that was the initial intention of the modifiers).

About the object fields it would require some extra metadata to be added to set those constraints in the schema.

[dud225]

So, in short, what you are requesting is to support a parameter to be provided in different types, for example string and boolean, that will be represented in the schema by an anyOf

Yes correct.

use the first one as the actual value for the parameter (that was the initial intention of the modifiers).

I'm not sure to get what you mean here.

[miguelaeh]

I'm not sure to get what you mean here

Currently, a modifier changes the default value or type that is shown in the README.md generating the Chart documentation. For example:

@param a.b.c [object] Parameter description

In order to avoid adding more tags that would be more complex, we could do something like:

@param a.b.c [object,array] Parameter description

While using the first one to render the documentation into the README.md. With that list of values we can generate the anyOf field

[dud225]

While using the first one to render the documentation into the README.md. With that list of values we can generate the anyOf field

OK got it, so the README won't list all the possibility, only the first one that would be considered the main type.

[miguelaeh]

I have been thinking a bit more about it, and the suggested approach would not be so simple since adding a modifier to a parameter will change its default value into the README.md, and it is not the desired default behavior. So probably, the best way to support this would be adding a new tag. In this case, it will need to be positional since it will affect the parameter specified by the previous @param tag, or it can include again the parameter path in order to make it not possitional.

[fmulero]

We will close this issue because it has more than 2 years without any update an there is no no similar requests or reactions from the community about this.