specs/data/README.md

specs/data/

Curated reference data for the Fugee country recommendation system.

Files

File	Description
countries.json	Master country dataset — 146 signatories + 23 non-signatories. Curated layer with asylum procedures, legal aid orgs, processing times, tier ratings.
countries_enriched.json	Generated — countries.json + UNHCR API stats (acceptance rates, application volumes, refugee populations). Run data/scripts/enrich_downloader.py to produce.

countries.json schema

{
  "_meta": { ... },
  "signatories": {
    "KEN": {
      "name", "iso3", "flag", "tier",
      "convention": { "1951", "1967", "oau_1969", "year", "notes" },
      "asylum_system": {
        "body", "unhcr_present", "unhcr_office", "procedure",
        "work_right", "education_right", "movement",
        "processing_months": { "min", "max", "typical" },
        "appeal", "legal_aid", "orgs", "steps", "docs_required"
      },
      "profile": { "languages", "hosts", "integration", "safety", "economic_access" },
      "stats": {
        "acceptance_rate_recent",
        "total_protection_rate_recent",
        "applications_last_year",
        "refugee_population_total",
        "data_year"
      }
    }
  },
  "non_signatories": {
    "UAE": {
      "tier": "non_signatory_viable_temporary",
      "alternative_pathways": { ... },
      "strategic_guidance": "..."
    }
  }
}

Tier system

Tier	Description
1	Major active system — full procedures, legal aid, contacts
2	Active system — moderate volume or significant for specific profiles
3	Functioning but low volume, primarily transit or origin
4	Signatory in name only — micro-state, collapsed, or non-functional

Non-signatory tiers: non_signatory_viable_temporary, non_signatory_skilled_only, non_signatory_resettlement_pipeline, non_signatory_not_recommended.