Skip to content

WW-79 (WING-76) — USAJOBS hiring-path & veterans'-preference codelist mapping

Spike research. Produced by fleet worker (grok kind, DESKTOP-D249KD4), 2026-07-24. Reviewed and committed by WT-2f62.

1) Scope

Enumerate USAJOBS codelists relevant to veteran hiring paths and preference, and map the veteran-relevant values to a neutral posting-chip taxonomy — chip label, which self-attested profile answer makes it relevant to surface (never a filter default), and the exact source codes. Hard rule carried through every recommendation below: chips are factual posting metadata — never sort keys, never scores, never eligibility verdicts. Eligibility comes from the posting + agency, not WorkWingman.

2) Chip mapping (summary — see full worker output for the raw codelist tables)

  • Primary chip source: HiringPath[] on each posting → chip ids hp-* (hp-vet for VET, hp-mspouse for MSPOUSE, hp-nguard for NGUARD, hp-disability, hp-special-authorities).
  • Secondary structured enrichment, only when the field is present: SpecialHiring → sh-* (e.g. sh-vra, sh-disvet30); VEOA-bearing WhoMayApply codes → wma-veoa.
  • MilitaryStatusCode is not posting metadata — it is a veteran's own preference claim (5/10/0 points). It never appears as a posting chip; it belongs to profile self-attestation + the apply-prep checklist (WW-82), never as "+10 points" copy.

3) Edge cases / anti-patterns worth keeping visible

Code / concept Action
PUBLIC, STUDENT, GRADUATES, SES, federal-employee paths, LAND, NATIVE, PEACE, OVERSEAS, NOPUBLIC, disabled FED / SE-OTHER No veteran chip. Optional non-vet path chips are out of this spike's GTM scope.
MilitaryStatusCode 1–7 on posting N/A — not posting fields. Profile only.
MilitaryStatusCode preference points (5/10/0) Never chip as "+10 points." Apply-prep checklist only (WW-82).
Free-text "VEOA" without WhoMayApply VEOA codes No wma-veoa chip in v1.
Free-text "30% disabled" without DISVET30 No sh-disvet30 chip in v1; hp-vet may still apply.
SPECIAL-AUTHORITIES without specialhirings rows Generic hp-special-authorities only.
Disabled-but-not-veteran Schedule A (SCHEDA / path DISABILITY) Disability chips only if product chooses; do not label "disabled veteran."

3.3 Search / ingest pitfalls

Pitfall Guidance
Search HiringPath=vet is a discovery filter, not a UI default Product may offer an explicit user-toggled filter later; chips still must not silently re-rank.
Case mismatch: API codes VET vs query vet Normalize to uppercase codes in storage; lowercase only at Search query build.
SpecialHiring / WhoMayApply field occupancy unknown without WW-78 sample Assume path codes are common; special-hiring/VEOA structured codes may be sparse — design chips to degrade gracefully.
Preference ≠ hiring path A veteran may claim CPS (6) while applying to a PUBLIC-only announcement; that is valid agency process, not a WW chip contradiction.

3.4 Copy anti-patterns (reject in review)

  • "You're eligible," "Strong match for veterans," "Preference boost," "+10."
  • Sorting jobs by number of veteran chips.
  • Auto-enabling HiringPath=vet because profile has mil.veteran.
  • Using chip count as a FitLevel input (FitLevel enum remains unchanged per WW-76).

4) Recommendation + open questions

4.1 Recommendation (implementation-ready for P2, still research)

  1. Primary chip source: normalize HiringPath[] from each USAJOBS job → chip ids hp-* per §2.1.
  2. Secondary structured enrichment: when present, map SpecialHiring → sh-* and VEOA-bearing WhoMayApply codes → wma-veoa.
  3. Do not treat MilitaryStatusCode as posting metadata; ship it as optional profile self-attestation + apply-prep document hints (DD-214, SF-15, DVA letter — codes already in requiredstandarddocuments / documentations codelists).
  4. VEOA / VRA / 30%+: only chip when exact codes in §2.1 are present; otherwise rely on hp-vet without overclaiming authority.
  5. Relevance: optional profile keys; highlight only; never default filter; never sort key.
  6. UI order (stable): hp-vet → sh-vra → sh-disvet30 → wma-veoa → hp-mspouse → hp-nguard → hp-disability → other. Order is navigational, not priority scoring.
  7. Telemetry (allowed): counts of chips shown and highlighted — not "eligibility conversion" hero metrics (WW-76 / WW-68 rule).
  8. Tests to require later: fixtures with multi-path postings; assert chips never enter sort comparator; assert unset profile never auto-filters; assert no preference-point copy.

4.2 Go / no-go on task GTM claim

Claim Verdict
"We can surface veteran hiring-path chips from USAJOBS codelists" Go — VET, MSPOUSE, NGUARD are first-class
"We can chip VEOA / VRA / 30% disabled as separate structured facts" Conditional go — via whomayapply + specialhirings, not via hiringpaths; depends on field population (WW-78)
"Military status codes let us label postings with preference points" No-go — wrong layer; profile/apply-prep only

4.3 Open questions (for WW-78 / P2 build / product)

  1. Field occupancy: On live Search fields=full (or Historic JOA), how often do jobs include SpecialHiring and numeric WhoMayApply codes vs only HiringPath? (Blocks how loud VEOA/VRA chips can be in the pitch.)
  2. Payload shape: Exact JSON paths for hiring paths and special hirings on Search vs Historic JOA — confirm in WW-78.
  3. Profile UX: Single multi-select "Military background" step vs reusing free-text VeteranStatus with structured sidecar? Privacy: keep local-first / optional (clearance caution already in WW-76).
  4. Collapse rules: Path MSPOUSE + special MILSPOUSE → one chip or two?
  5. Disability chip scope: Include hp-disability / Schedule A in veteran GTM surface, or keep disability chips on a separate accessibility track?
  6. NLP free-text (v2+)? Developer synonym lists tempt regex for VEOA/VRA/30%. Recommend no for v1 — high false-positive risk against Kerr eligibility-oracle ban. Revisit only with evaluation set.
  7. Codelist refresh: Unauth endpoints + lastmodified query exist — cache cadence (weekly?) and disabled-flag handling (FED, SE-OTHER).
  8. User-toggled Search filters: If product later offers "only announcements that list veterans path," make it an explicit control, separate from chip rendering, with clear "this hides other jobs" copy.

5. URL citation index (every URL fetched this spike)

  1. https://data.usajobs.gov/api/codelist/hiringpaths
  2. https://data.usajobs.gov/api/codelist/militarystatuscodes
  3. https://data.usajobs.gov/api/codelist/specialhirings
  4. https://data.usajobs.gov/api/codelist/whomayapply
  5. https://data.usajobs.gov/api/codelist/disabilities (adjacent; not used for chips)
  6. https://data.usajobs.gov/api/codelist/servicetypes
  7. https://data.usajobs.gov/api/codelist/requiredstandarddocuments
  8. https://data.usajobs.gov/api/codelist/documentations
  9. https://data.usajobs.gov/api/codelist/federalemploymentstatuses
  10. https://data.usajobs.gov/api/codelist/positionofferingtypes
  11. https://data.usajobs.gov/api/Search (401 without key — auth confirmed)
  12. https://developer.usajobs.gov/api-reference/
  13. https://developer.usajobs.gov/API-Reference/GET-Codelist-hiringpaths
  14. https://developer.usajobs.gov/API-Reference/GET-Codelist-militarystatuscodes
  15. https://developer.usajobs.gov/API-Reference/GET-Codelist-specialhirings
  16. https://developer.usajobs.gov/API-Reference/GET-api-Search
  17. https://developer.usajobs.gov/general/hiring-paths
  18. https://www.usajobs.gov/Help/working-in-government/unique-hiring-paths/veterans/
  19. https://www.usajobs.gov/Help/working-in-government/unique-hiring-paths/veterans/veo/
  20. https://www.usajobs.gov/Help/working-in-government/unique-hiring-paths/veterans/vra/
  21. https://www.usajobs.gov/Help/working-in-government/unique-hiring-paths/veterans/preference/
  22. https://www.usajobs.gov/Help/working-in-government/unique-hiring-paths/military-spouses/
  23. https://www.usajobs.gov/Help/working-in-government/unique-hiring-paths/national-guard-reserves/
  24. https://www.opm.gov/policy-data-oversight/veterans-services/vet-guide-for-hr-professionals/

Bottom line

  • Hiring paths give clean chips for veterans, military spouses, and National Guard & Reserves.
  • VEOA / VRA / 30%+ need other codelists (whomayapply, specialhirings) and must not be faked from path VET alone.
  • Military status codes are preference self-claims, not posting labels — use for profile relevance + apply prep, never as ranking or eligibility oracles.
  • Chips remain factual metadata; eligibility stays with the posting + agency.

Jira WING-76 · Vikunja · BOARD.md