Jaymerry/french-administrative-hierarchy-data-quality

French Administrative Hierarchy Data Quality Benchmark

A reproducible benchmark for evaluating the validation, classification, and repair of French administrative geographic records.

The dataset is derived from the INSEE Code officiel géographique (COG) 2026 and focuses on the hierarchical relationship:

Region → Department → Commune

Important: commune_code is an INSEE/COG administrative identifier, not a postal code. This dataset is not intended for postal-address validation or postal-code prediction.

1. What the dataset models

Each source record represents a canonical French administrative path:

Region → Department → Commune

Example:

Auvergne-Rhône-Alpes (84)
└── Rhône (69)
    └── Lyon (69123)

The benchmark evaluates whether the codes and labels in a record form a valid and internally consistent administrative hierarchy.

A record may contain values that are individually valid but incorrectly combined. For example:

Region:      Auvergne-Rhône-Alpes (84)
Department:  Isère (38)
Commune:     Lyon (69123)

Department 38 and commune code 69123 both exist, but Lyon does not belong to Isère. The anomaly is therefore hierarchical, rather than purely syntactic.

The word hierarchy refers here to administrative and geographic membership. It does not imply organizational ownership or historical lineage.

2. Record structure

The input-oriented fields are the corrupted_* columns. The clean_* columns and evaluation labels describe the expected canonical record.

Core fields include:

Example

Canonical record:

{
  "region_code": "84",
  "department_code": "69",
  "commune_code": "69123",
  "commune_name": "Lyon"
}

Altered record:

{
  "region_code": "84",
  "department_code": "38",
  "commune_code": "69123",
  "commune_name": "Lyon",
  "quality_status": "inconsistent",
  "error_type": "mismatched_department",
  "affected_field": "department_code",
  "expected_value": "69",
  "corrupted_value": "38"
}

3. Quality statuses

The benchmark distinguishes exact canonical form from actual integrity failures.

This distinction matters because a spelling such as Saint-Etienne may be non-canonical without being unusable in every information system.

has_integrity_error is therefore stricter than is_canonical.

4. Main error types

Why the distinction between unknown and mismatched codes matters

• —unknown_commune_code: the identifier does not exist in COG 2026.
• —mismatched_commune_code: the identifier exists, but it does not identify the commune named in the record.

The second task requires entity-level consistency checking rather than a simple lookup.

5. What the benchmark evaluates

The dataset supports several evaluation tasks:

1. 1.Canonical-form detection Determine whether the presented record exactly matches the official form.

1. 1.Integrity-error detection Identify records containing invalid identifiers or cross-field inconsistencies.

1. 1.Error-type classification Classify the synthetic anomaly.

1. 1.Affected-field identification Determine which field should be repaired.

1. 1.Hierarchical consistency checking Verify the administrative path Region → Department → Commune.

1. 1.Referential-integrity validation Check whether identifiers exist in the official reference.

1. 1.Value repair Recover the expected canonical value.

Suggested metrics

For binary detection:

• —Precision
• —Recall
• —F1
• —Matthews correlation coefficient

For error classification:

• —Macro-F1
• —Per-class precision and recall
• —Confusion matrix

For repair:

• —Exact repair accuracy
• —Field-level accuracy
• —Character error rate for commune names

Results should be reported by both error_type and difficulty.

6. Dataset configurations

full

Contains the complete generated distribution, including canonical records, spelling variants, and integrity errors.

Recommended for:

• —exploratory analysis;
• —multi-task learning;
• —studying the natural distribution produced by the generator.

integrity_only

Excludes simple non_canonical spelling variants.

Recommended for:

• —strict administrative consistency checking;
• —referential-integrity validation;
• —hierarchical anomaly detection.

binary_balanced

Contains one canonical and one altered record per source commune.

Recommended for:

• —balanced canonical-versus-altered classification;
• —baseline binary models;
• —controlled model comparison.

error_type_balanced

Balances each error type independently inside each split.

Recommended for:

• —multiclass benchmarking;
• —macro-F1 comparison;
• —reducing majority-class effects.

7. Typical use cases

Potential applications include:

• —data-quality pipelines;
• —ETL and ELT validation;
• —master-data management;
• —entity resolution;
• —record linkage;
• —referential-integrity testing;
• —anomaly detection;
• —tabular machine-learning benchmarks;
• —LLM and agent evaluation on structured records;
• —automated repair suggestions.

This benchmark is particularly relevant when a system must reason over the combination of several valid fields rather than validate each field independently.

Loading the dataset

Default configuration

from datasets import load_dataset

dataset = load_dataset(
    "Jaymerry/french-administrative-hierarchy-data-quality"
)

print(dataset)
print(dataset["train"][0])

Select a configuration

from datasets import load_dataset

dataset = load_dataset(
    "Jaymerry/french-administrative-hierarchy-data-quality",
    "integrity_only",
)

Available configurations:

full
integrity_only
binary_balanced
error_type_balanced

Load the auxiliary JSONL files

Parquet files under data/ are the files configured for the Hugging Face Dataset Viewer.

Equivalent human-readable JSONL files may be provided under jsonl/:

from datasets import load_dataset

dataset_jsonl = load_dataset(
    "json",
    data_files={
        "train": (
            "hf://datasets/"
            "Jaymerry/french-administrative-hierarchy-data-quality/"
            "jsonl/full/train.jsonl"
        ),
        "validation": (
            "hf://datasets/"
            "Jaymerry/french-administrative-hierarchy-data-quality/"
            "jsonl/full/validation.jsonl"
        ),
        "test": (
            "hf://datasets/"
            "Jaymerry/french-administrative-hierarchy-data-quality/"
            "jsonl/full/test.jsonl"
        ),
    },
)

Splits and leakage prevention

Splits are assigned at the source-record level using a deterministic hash.

All variants generated from the same commune remain in the same split. This prevents a model from seeing one altered version of a commune during training and another version of the same commune during evaluation.

The available splits are:

train
validation
test

Source and provenance

• —Producer: Institut national de la statistique et des études économiques (INSEE)
• —Source: Code officiel géographique au 1 January 2026
• —Source file: v_commune_2026.csv
• —Original license: Licence Ouverte / Open Licence 2.0
• —Dataset license: etalab-2.0
• —Generation seed: 42

The source is filtered to records where TYPECOM == "COM".

All alterations in this benchmark are generated synthetically. They must not be interpreted as errors present in the original INSEE data.

The repository includes generation and validation scripts as well as source and quality manifests for reproducibility.

Limitations

• —The benchmark represents the COG 2026 snapshot and does not automatically reflect later administrative changes.
• —The alterations are synthetic and do not cover every real-world data-entry process.
• —Difficulty labels are heuristic.
• —Accentless or hyphenless forms are labelled non_canonical, not universally invalid.
• —The current version focuses mainly on commune identifiers, commune names, and department consistency.
• —Region and department names may not yet be included as explicit columns.
• —This dataset is not intended for postal routing, postal-code validation, address geocoding, or operational administrative decisions.
• —The dataset must not replace the current official INSEE reference.

Responsible use

Appropriate uses include research, benchmarking, education, and development of data-quality systems.

Users should verify results against the latest official reference before applying corrections to production administrative data.

Reproducibility

The repository may include:

scripts/build_dataset_v2.py
scripts/validate_dataset_v2.py
metadata/source_manifest_2026.json
metadata/quality_report_v2.json
metadata/validation_report.json

The source manifest records the retrieval date and SHA-256 checksum of the original source file.

Citation

No formal paper is currently associated with this dataset.

When using it, please cite:

1. 1.the INSEE Code officiel géographique source;
2. 2.this Hugging Face dataset repository.

Suggested citation:

@dataset{merry_2026_french_administrative_hierarchy,
  author       = {Jeremy Banchet (Jaymerry)},
  title        = {French Administrative Hierarchy Data Quality Benchmark},
  year         = {2026},
  publisher    = {Hugging Face},
  url          = {https://huggingface.co/datasets/Jaymerry/french-administrative-hierarchy-data-quality}
}

License

The dataset is distributed under the Licence Ouverte / Open Licence 2.0, represented on Hugging Face by:

etalab-2.0

See SOURCES.md and the source manifest for detailed attribution and provenance.