PolicyEngine / PolicyEngine/policyengine-us

Audit incomplete metadata on container parameters

Open
#9,377 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
162
Forks
212
Avg merge
3d 3h
Merged PRs (30d)
97

Description

## Problem

The metadata-propagation audit in #5208 found parameter containers for which the parent does not supply enough source metadata to establish the expected child metadata. These are not propagation failures: there is no valid parent field to copy, or the declared field itself is malformed.

Known findings from the processed PolicyEngine US parameter tree:

- `openfisca.completed_programs.state` declares a `state_code` breakdown but has no unit or period; its 59 value-bearing children contain lists of program names.
- 45 breakdown containers lack a parent `period`. Each needs review because the correct period depends on the parameter's meaning.
- `gov.states.dc.tax.income.credits.ctc.income_threshold` declares `currency_USD` rather than the canonical `currency-USD` unit.
- Some multidimensional containers have no `breakdown` declaration even though their child keys represent filing statuses, counties, household sizes, or other dimensions. These require semantic review before adding breakdown metadata because breakdown declarations also control structure validation and completion.

## Required work

- Audit container parameters for missing or invalid `unit`, `period`, and `breakdown` metadata.
- Establish the intended metadata from parameter meaning and usage rather than inferring it only from child names.
- Correct source metadata where the intended value is established.
- Add validation that detects malformed unit names and any classes of missing metadata that can be required without false positives.
- Keep policy values and calculation behavior unchanged.

Selective metadata propagation, including the deferred SNAP asset-limit case, is tracked separately in PolicyEngine/policyengine-core#537.

Contributor guide

Open the contributing guide

Research direction

Start by reviewing the metadata-propagation audit in #5208 and the processed PolicyEngine US parameter tree, including the listed containers and malformed unit. Done means correcting only source metadata where its intended value is established, adding validation without false positives, and leaving policy values and calculation behavior unchanged.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
data
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.