Proposal: Add region metadata to support hierarchical selection (country → region → subregion)

[HanSolo72]

Summary

I would like to propose an extension to the holiday definitions to include structured region metadata. The goal is to enable hierarchical region selection (e.g. country → state → special cases) for applications that consume the holidays gem.

Currently, regions are available as flat identifiers (e.g. :de, :de_by, :de_by_cath), which works well for calculation, but makes it difficult to build user interfaces that guide users through valid region selections.

Motivation

In real-world applications (e.g. helpdesk systems like Zammad), users often need to configure public holidays via a GUI.

A flat list of region codes is not sufficient for this use case. For example:

• Germany (de)

  • Bavaria (de_by)

    • Predominantly Catholic (de_by_cath)
    • Augsburg (de_by_augsburg)

  • Berlin (de_be) → no further selection needed

A hierarchical structure would allow:

• dynamic dropdowns
• guided user selection
• avoiding invalid or nonsensical combinations

Proposal

Introduce optional metadata for regions that describes:

• display name
• parent-child relationships
• region type (country, state, locality, special_rule)
• whether the region is selectable

Example (conceptual):

regions_meta:
  - code: de
    name: Germany
    type: country
    parent:

  - code: de_by
    name: Bavaria
    type: state
    parent: de

  - code: de_by_cath
    name: Predominantly Catholic
    type: special_rule
    parent: de_by

Storage Options

There are two possible approaches:

1. Store metadata inside each country YAML file (e.g. de.yaml)
2. Maintain a global metadata file

I would prefer option 1, since:

• data stays close to the relevant country
• avoids duplication
• easier to maintain consistency

Performance Consideration

To avoid parsing all YAML files at runtime, a generated index (e.g. during build) could be used for fast lookup.

Benefits

• enables UI-driven region selection
• improves usability for integrations
• keeps backward compatibility (metadata is optional)
• does not affect existing holiday calculation logic

Open Questions

• Would you accept region metadata in the definitions?
• Do you have a preferred structure or format?
• Would a generated index be acceptable as part of the build process?

I would be happy to contribute an initial implementation if this approach aligns with the project direction.