Add admin_level to divisions

[stepps00]

Will replace #414.

A. Expected release date

Feb 2026

Description

This change:

• adds a new admin_level field (int value) representing the division’s position in its country’s hierarchy
• sets that new field as required for top-level subtypes; country, macroregion, region, macrocounty, and county
• keeps the existing subtype schema in tact
• updates relevant examples and counterexamples
• regenerates the pydantic baseline schema files

Checklist

Checklist of tasks commonly-associated with schema pull requests. Please review the relevant checklists and ensure you do all the tasks that are required for the change you made.

1. Add relevant examples.
2. Add relevant counterexamples.
3. Update any counterexamples that became obsolete. For example, if a counterexample uses property A but is not intended to test property A's validity, and you made a schema change that invalidates property A in that counterexample, fix the counterexample to align it with your schema change.
4. Update in-schema documentation using plain English written in complete sentences, if an update is required.
5. Update Docusaurus documentation, if an update is required.
6. Review change with Overture technical writer to ensure any advanced documentation needs will be taken care of, unless the change is trivial and would not affect the documentation.

Documentation website

Update the hyperlink below to put the pull request number in.

Docs preview for this PR.

[vcschapp]

I'm aligned, this seems right!

I'm clicking request changes because ... shouldn't admin_level be a required field on all three feature types? If it is fully derived from the level in the feature hierarchy, which I think it is, then there's no reason why every feature shouldn't have it is there?

[vcschapp]

@stepps00 , we just merged the pydantic branch onto dev - can you please also include the Pydantic version of your change in this PR?

[stepps00]

shouldn't admin_level be a required field on all three feature types? If it is fully derived from the level in the feature hierarchy, which I think it is, then there's no reason why every feature shouldn't have it is there?

So I'm hesitant to mark this as required for all fields. Two main reasons:

• This assumes that all divisions exist and are present in the dataset today, which isn't necessarily the case. If, for whatever reason, the theme is missing a top-level (admin1, admin2) feature, then all descendants of that feature would have incorrect (+1) admin_level values. I think we'd want to use a per-country lookup table to derive these values.
• Do things like neighborhoods and microhoods need an admin_level? Probably not - this admin_level field is helpful to top-level (above locality) features where admin levels are typically defined.. but I'm not sure we're interested in maintaining values for lower-level subtypes.

Edit: See comment below; I've set this as required for relevant subtypes.

we just merged the pydantic branch onto dev - can you please also include the Pydantic version of your change in this PR?

This should be complete in the two most recent commits in this branch.. I'll take a look at the validation failures.

[stepps00]

shouldn't admin_level be a required field on all three feature types? If it is fully derived from the level in the feature hierarchy, which I think it is, then there's no reason why every feature shouldn't have it is there?

Update: in the most recent set of commits, I've set this new field as a required property on subtypes above localadmin in the subtype hierarchy (example). Validation should now pass with a updated Pydantic baseline schema files.

[stepps00]

I'm clicking request changes because ... shouldn't admin_level be a required field on all three feature types? If it is fully derived from the level in the feature hierarchy, which I think it is, then there's no reason why every feature shouldn't have it is there?

@vcschapp after reviewing the divisions data, specifically the number of entries in the hierarchy for each country's set of subtypes, we should be confident in using the number of hierarchy entries to derive the admin_level value for the top-level admin layers - admin0, admin1, and admin2 (minus features in countries with X* country codes).

Of these 42,974 features at the admin0, admin1, and admin2 levels, only 15 have an unexpected number of entries in their hierarchies. Meaning we'd see a small error rate when using this to calculate the admin_level value for this set of features.

Beyond this (admin3, admin4, etc), there are various data inconsistencies that we'd need to fix before supporting this value on every division feature. For now, the theme is interested in supporting those top-level admin_level additions (0-2). I think this means this pull request is okay as-is.. but happy to discuss further.

[vcschapp]

Of these 42,974 features at the admin0, admin1, and admin2 levels, only 15 have an unexpected number of entries in their hierarchies. Meaning we'd see a small error rate when using this to calculate the admin_level value for this set of features.

Is the conclusion that we will use the hierarchy level method to calculate admin_level and accept that 15 entries are misclassified?

[vcschapp]

                            ______________________________________________
                         .-'                     _                        '.
                       .'                       |-'                        |
                     .'                         |                          |
                  _.'               p         _\_/_         p              |
               _.'                  |       .'  |  '.       |              |
          __..'                     |      /    |    \      |              |
    ___..'                         .T\    ======+======    /T.             |
 ;;;\::::                        .' | \  /      |      \  / | '.           |
 ;;;|::::                      .'   |  \/       |       \/  |   '.         |
 ;;;/::::                    .'     |   \       |        \  |     '.       |
       ''.__               .'       |    \      |         \ |       '.     |
            ''._          <_________|_____>_____|__________>|_________>    |
                '._     (___________|___________|___________|___________)  |
                   '.    \;;;Dani;;;o;;;;;o;;;;;o;;;;;o;;;;;o;;;;;o;;;;/   |
                     '.~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~   |
                       '. ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~  |
                         '-.______________________________________________.'

[vcschapp]

This PR has received approvals from all 4 Steering Members. (Jonah approved but approval was washed out by one of the final tweak updates last night.)

Merging.