{
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "$id": "https://traveldecla.com/data/citizenship/schema.json",
 "title": "Country citizenship acquisition record",
 "description": "One record per country: how a foreigner or a descendant can become a citizen. Baseline: GLOBALCIT Citizenship Law Dataset v3.1 (law in force on 1 Jan 2024), updated with post-2024 changes.",
 "type": "object",
 "required": [
  "iso3",
  "name",
  "slug",
  "naturalisation_summary",
  "dual_citizenship",
  "routes",
  "review"
 ],
 "properties": {
  "iso2": {
   "type": [
    "string",
    "null"
   ],
   "pattern": "^[A-Z]{2}$"
  },
  "iso3": {
   "type": "string",
   "pattern": "^[A-Z]{3}$"
  },
  "name": {
   "type": "string"
  },
  "slug": {
   "type": "string",
   "description": "URL slug, e.g. /citizenship/{slug}/"
  },
  "region": {
   "type": "string"
  },
  "naturalisation_summary": {
   "type": "object",
   "description": "Current view of ordinary (residence-based) naturalisation. In-force changes are applied; see baseline for the 2024 values.",
   "properties": {
    "residence_years": {
     "type": [
      "integer",
      "null"
     ],
     "description": "Nominal years of residence; null = no residence-based route"
    },
    "renunciation_of_other_citizenship": {
     "enum": [
      "no_requirement",
      "nominal_requirement",
      "required_with_major_exceptions",
      "required",
      "no_naturalisation",
      null
     ]
    },
    "language_requirement": {
     "enum": [
      "none",
      "general_assimilation",
      "required_no_test",
      "required_with_test",
      "no_naturalisation",
      null
     ]
    },
    "civic_knowledge_requirement": {
     "enum": [
      "none",
      "required_no_test",
      "required_with_test",
      "no_naturalisation",
      null
     ]
    },
    "criminal_record_condition": {
     "type": [
      "boolean",
      "null"
     ]
    },
    "economic_resources_condition": {
     "type": [
      "boolean",
      "null"
     ]
    },
    "residence_years_note": {
     "type": [
      "string",
      "null"
     ],
     "description": "Shorter or different periods for some groups"
    }
   }
  },
  "dual_citizenship": {
   "type": "object",
   "properties": {
    "overall": {
     "enum": [
      "not_accepted",
      "accepted_for_citizens_abroad_only",
      "accepted_for_new_citizens_only",
      "accepted",
      null
     ]
    },
    "new_citizens_must_renounce": {
     "type": [
      "string",
      "null"
     ]
    },
    "citizens_who_naturalise_abroad": {
     "enum": [
      "no_loss",
      "loss_lapse",
      "loss_lapse_with_exceptions",
      "loss_naturalised_only",
      "loss_withdrawal",
      "loss_withdrawal_with_exceptions",
      "loss_naturalised_only_withdrawal",
      null
     ]
    },
    "rule_citizens_abroad": {
     "type": [
      "string",
      "null"
     ]
    }
   }
  },
  "investment_route": {
   "type": "boolean"
  },
  "routes": {
   "type": "array",
   "description": "All acquisition routes, fixed order. Route ids: naturalisation, marriage, descent, birth_in_country, child_of_new_citizen, adoption, other_relatives, former_citizens, specific_nationalities, cultural_affinity, childhood_residence, very_long_residence, refugees, stateless, special_achievement, public_service, investment.",
   "items": {
    "type": "object",
    "required": [
     "id",
     "label",
     "available",
     "provisions"
    ],
    "properties": {
     "id": {
      "type": "string"
     },
     "label": {
      "type": "string"
     },
     "available": {
      "type": "boolean"
     },
     "provisions": {
      "type": "array",
      "items": {
       "type": "object",
       "properties": {
        "mode": {
         "type": "string",
         "description": "GLOBALCIT mode id, e.g. A06a"
        },
        "mode_label": {
         "type": "string"
        },
        "available": {
         "type": "boolean"
        },
        "procedure": {
         "type": [
          "string",
          "null"
         ],
         "description": "Attribution (automatic), Application (entitlement), Grant (discretionary)..."
        },
        "category": {
         "type": [
          "string",
          "null"
         ]
        },
        "rule": {
         "type": [
          "string",
          "null"
         ],
         "description": "Plain-English rule as coded by GLOBALCIT (law as of 1 Jan 2024)"
        },
        "legal_reference": {
         "type": [
          "string",
          "null"
         ],
         "description": "Article(s) of the nationality law"
        }
       }
      }
     }
    }
   }
  },
  "changes_since_baseline": {
   "type": "array",
   "items": {
    "type": "object",
    "properties": {
     "id": {
      "type": "string"
     },
     "date": {
      "type": "string",
      "format": "date"
     },
     "status": {
      "enum": [
       "in_force",
       "scheduled",
       "adopted_pending",
       "proposed"
      ]
     },
     "confidence": {
      "enum": [
       "official",
       "secondary",
       "needs_check"
      ]
     },
     "summary": {
      "type": "string"
     },
     "sources": {
      "type": "array",
      "items": {
       "type": "string",
       "format": "uri"
      }
     },
     "fields_changed": {
      "type": "array"
     }
    }
   }
  },
  "official_sources": {
   "type": "array",
   "items": {
    "type": "object",
    "properties": {
     "url": {
      "type": "string"
     },
     "title": {
      "type": "string"
     },
     "kind": {
      "type": "string"
     },
     "found": {
      "type": "string"
     }
    }
   }
  },
  "baseline": {
   "type": "object",
   "description": "Snapshot of summary fields exactly as coded by GLOBALCIT for 1 Jan 2024"
  },
  "review": {
   "type": "object",
   "properties": {
    "baseline": {
     "type": "string"
    },
    "law_in_force_as_of": {
     "type": "string"
    },
    "status": {
     "enum": [
      "verified",
      "verified_with_corrections",
      "needs_review"
     ],
     "description": "verified: key facts match an independent second source. verified_with_corrections: a key fact was corrected against the law text or an official source. needs_review: the second source disagrees, see verification_note."
    },
    "last_checked": {
     "type": [
      "string",
      "null"
     ]
    },
    "indexable": {
     "type": "boolean",
     "description": "Page is indexable and in the sitemap only when true"
    },
    "notes": {
     "type": [
      "string",
      "null"
     ]
    },
    "attribution": {
     "type": "string"
    },
    "verified": {
     "type": "boolean",
     "description": "True when status is verified or verified_with_corrections"
    },
    "verification_note": {
     "type": [
      "string",
      "null"
     ],
     "description": "What the cross-check found, or where the sources disagree"
    },
    "cross_check_sources": {
     "type": "array",
     "items": {
      "type": "string"
     },
     "description": "Independent second sources used for the cross-check"
    },
    "method": {
     "type": [
      "string",
      "null"
     ],
     "description": "How the record was checked"
    }
   }
  }
 },
 "x-verification-fields": {
  "review.status": "verified | verified_with_corrections | needs_review",
  "review.verified": "boolean",
  "review.verification_note": "string shown to readers when needs_review",
  "review.cross_check_sources": "array of URLs",
  "review.method": "string",
  "dual_citizenship.has_exceptions": "boolean",
  "naturalisation_summary.residence_years_note": "string (optional)",
  "provisions[].superseded_by": "array of change ids (optional)",
  "provisions[].corrected": "date (optional)"
 }
}