docs(settings-gen): add applies_to and nested settings to schema

[theletterf]

Summary

• Document applies_to support in the settings-gen YAML schema, including both mapping and inline list forms.
• Document nested settings support for hierarchical settings, including inheritance and overrides.
• Add a fully worked example showing multiple applies_to statements.

Closes #250871.

LLM usage

This PR was drafted with assistance from an LLM (OpenAI GPT-5.2).

Made with Cursor

[github-actions]

🔍 Preview links for changed docs

• docs/settings-gen/readme.md

[kilfoyle]

Thanks @theletterf! This looks great!

One question: Do we have examples of nested settings in the docs currently? I'm aware of nested groups of settings, but I think perhaps that's a separate problem. Taking the Kibana Security settings as an example, we currently have nested groups of settings:

• Security settings in Kibana (YAML file)
  • Authentication security settings (group within Yaml file)
    • Valid settings for all authentication providers
    • SAML authentication provider settings
      • Discontinued SAML settings
    • OpenID Connect authentication provider settings
      ...
  • Encrypted saved object settings (group within Yaml file
    • Audit logging settings
    • File appender
    • Rolling file appender

I'm not sure how we'd support this case, or perhaps we should limit our yaml so that we don't support nesting groups in this way.

[kilfoyle]

I really like the applies_to support!

[kilfoyle]

As I think about it, the nested settings could be useful for documenting the yaml config files used in the various ingest tools!

[florent-leborgne]

Nice one @theletterf. The main thing that comes to mind right now is the redundancy between keys:

• applies_to
• status
• platforms

If we add applies_to, then the 2 others become irrelevant. I think we should keep either applies_to, or status + platforms
What could be interesting if we keep the latter is that it's a bit more semantic. I'm open to different perspective here :)

The second point is that they should be mandatory. For example, maybe we want to force the "platforms" (or applies_to > deployments) to be clearly defined as available or unavailable, so that there's no surprise or doubt when something is not specified.

Happy to help brainstorm.

[theletterf]

@florent-leborgne Following @kilfoyle 's suggestions, I've removed platform and status from the schema —- agree that they're redundant.

@kilfoyle As per your last comment, are you happy with the proposed nesting mechanisms then? Would you also like to have support for nested groups?

[florent-leborgne]

We also talked about being able to specify default values, that can potentially be different per deployment/project type (maybe that's a different issue?)

[theletterf]

It's a good idea, but perhaps we could wait till we try apply the schema?

[kilfoyle]

LGTM! 🚀 Thank you.

I agree with Florent that the applies_to should be mandatory.

Are you happy with the proposed nesting mechanisms then? Would you also like to have support for nested groups?

Yes! I was thinking that the intent was to solve the nested groups issue, but I think probably this was intended for the "yaml config file" settings use case. No harm in supporting that. :-) For now I don't think nested groups is a requirement because it would add a lot of unwanted complexity to the yaml.

[florent-leborgne]

LGTM, just commenting because I have some final comments to simplify

[theletterf]

@florent-leborgne Applied, thanks!!

[florent-leborgne]

LGTM thanks! Let's see later for defaults handling