ISO 3166-1 Alpha-2 Country Code

{
  "id": "https://w3id.org/dartfx/semanticdt/library/global/iso3166-2_codes",
  "name": "ISO 3166-1 Alpha-2 Country Code",
  "description": "Two-letter country codes defined in ISO 3166-1, representing countries, dependent territories, and special areas of geographical interest. Includes user-assigned private-use code extensions (AA, QM-QZ, XA-XZ, and ZZ).",
  "version": "0.1.0",
  "concepts": [
    {
      "uri": "https://www.wikidata.org/wiki/Q1140221",
      "vocabulary": "Wikidata",
      "pref_label": "ISO 3166-1 alpha-2",
      "match_type": "exactMatch"
    }
  ],
  "storage_types": [
    {
      "target_environment": "generic",
      "data_type": "string"
    },
    {
      "target_environment": "python",
      "data_type": "str"
    },
    {
      "target_environment": "sql",
      "data_type": "CHAR",
      "format_modifier": 2
    },
    {
      "target_environment": "xsd",
      "data_type": "string"
    }
  ],
  "classification": {
    "name": "ISO-3166-1",
    "uri": "https://www.iso.org/iso-3166-country-codes.html",
    "version": "3166-1:2020"
  },
  "validation_rules": [
    {
      "rule_type": "regex",
      "pattern": "^[A-Z]{2}$",
      "message": "Country Code must consist of exactly 2 uppercase letters."
    },
    {
      "rule_type": "custom",
      "message": "Invalid ISO 3166-1 alpha-2 country code (or private-use code).",
      "code_snippets": [
        {
          "target_environment": "python",
          "code": "def validate_iso3166_2_codes(val: str) -> bool:\n    clean = val.strip().upper()\n    if clean in {\"AA\", \"ZZ\"}:\n        return True\n    if len(clean) == 2:\n        if clean[0] == 'Q' and 'M' <= clean[1] <= 'Z':\n            return True\n        if clean[0] == 'X' and 'A' <= clean[1] <= 'Z':\n            return True\n    valid_codes = {\n        \"AD\", \"AE\", \"AF\", \"AG\", \"AI\", \"AL\", \"AM\", \"AO\", \"AQ\", \"AR\", \"AS\", \"AT\", \"AU\", \"AW\", \"AX\", \"AZ\",\n        \"BA\", \"BB\", \"BD\", \"BE\", \"BF\", \"BG\", \"BH\", \"BI\", \"BJ\", \"BL\", \"BM\", \"BN\", \"BO\", \"BQ\", \"BR\", \"BS\",\n        \"BT\", \"BV\", \"BW\", \"BY\", \"BZ\", \"CA\", \"CC\", \"CD\", \"CF\", \"CG\", \"CH\", \"CI\", \"CK\", \"CL\", \"CM\", \"CN\",\n        \"CO\", \"CR\", \"CU\", \"CV\", \"CW\", \"CX\", \"CY\", \"CZ\", \"DE\", \"DJ\", \"DK\", \"DM\", \"DO\", \"DZ\", \"EC\", \"EE\",\n        \"EG\", \"EH\", \"ER\", \"ES\", \"ET\", \"FI\", \"FJ\", \"FK\", \"FM\", \"FO\", \"FR\", \"GA\", \"GB\", \"GD\", \"GE\", \"GF\",\n        \"GG\", \"GH\", \"GI\", \"GL\", \"GM\", \"GN\", \"GP\", \"GQ\", \"GR\", \"GS\", \"GT\", \"GU\", \"GW\", \"GY\", \"HK\", \"HM\",\n        \"HN\", \"HR\", \"HT\", \"HU\", \"ID\", \"IE\", \"IL\", \"IM\", \"IN\", \"IO\", \"IQ\", \"IR\", \"IS\", \"IT\", \"JE\", \"JM\",\n        \"JO\", \"JP\", \"KE\", \"KG\", \"KH\", \"KI\", \"KM\", \"KN\", \"KP\", \"KR\", \"KW\", \"KY\", \"KZ\", \"LA\", \"LB\", \"LC\",\n        \"LI\", \"LK\", \"LR\", \"LS\", \"LT\", \"LU\", \"LV\", \"LY\", \"MA\", \"MC\", \"MD\", \"ME\", \"MF\", \"MG\", \"MH\", \"MK\",\n        \"ML\", \"MM\", \"MN\", \"MO\", \"MP\", \"MQ\", \"MR\", \"MS\", \"MT\", \"MU\", \"MV\", \"MW\", \"MX\", \"MY\", \"MZ\", \"NA\",\n        \"NC\", \"NE\", \"NF\", \"NG\", \"NI\", \"NL\", \"NO\", \"NP\", \"NR\", \"NU\", \"NZ\", \"OM\", \"PA\", \"PE\", \"PF\", \"PG\",\n        \"PH\", \"PK\", \"PL\", \"PM\", \"PN\", \"PR\", \"PS\", \"PT\", \"PW\", \"PY\", \"QA\", \"RE\", \"RO\", \"RS\", \"RU\", \"RW\",\n        \"SA\", \"SB\", \"SC\", \"SD\", \"SE\", \"SG\", \"SH\", \"SI\", \"SJ\", \"SK\", \"SL\", \"SM\", \"SN\", \"SO\", \"SR\", \"SS\",\n        \"ST\", \"SV\", \"SX\", \"SY\", \"SZ\", \"TC\", \"TD\", \"TF\", \"TG\", \"TH\", \"TJ\", \"TK\", \"TL\", \"TM\", \"TN\", \"TO\",\n        \"TR\", \"TT\", \"TV\", \"TW\", \"TZ\", \"UA\", \"UG\", \"UM\", \"US\", \"UY\", \"UZ\", \"VA\", \"VC\", \"VE\", \"VG\", \"VI\",\n        \"VN\", \"VU\", \"WF\", \"WS\", \"YE\", \"YT\", \"ZA\", \"ZM\", \"ZW\"\n    }\n    return clean in valid_codes\n"
        }
      ]
    }
  ],
  "agent_instructions": {
    "guidelines": "Country codes represent geospatial regions. Normalize by converting to uppercase. Note that AA, QM-QZ, XA-XZ, and ZZ are reserved for private use / user assignment, and should be accepted as valid.",
    "system_prompt_snippet": "Ensure country codes are valid ISO-3166-1 Alpha-2 uppercase strings (or private-use codes AA, QM-QZ, XA-XZ, ZZ)."
  },
  "scope": {
    "geospatial_coverage": {
      "description": "Global",
      "codes": [
        "Global"
      ]
    },
    "domain": "Geographic / Classification",
    "governing_institution": "ISO"
  },
  "display_format": {
    "display_template": "{{ value.upper() }}"
  },
  "examples": [
    {
      "value": "US",
      "is_valid": true,
      "description": "Valid country code for United States."
    },
    {
      "value": "CA",
      "is_valid": true,
      "description": "Valid country code for Canada."
    },
    {
      "value": "ca",
      "is_valid": true,
      "description": "Valid country code for Canada (needs conversion to uppercase)."
    },
    {
      "value": "AA",
      "is_valid": true,
      "description": "Valid private-use country code (user assignment AA)."
    },
    {
      "value": "QX",
      "is_valid": true,
      "description": "Valid private-use country code (user assignment within QM-QZ range)."
    },
    {
      "value": "XZ",
      "is_valid": true,
      "description": "Valid private-use country code (user assignment within XA-XZ range)."
    },
    {
      "value": "ZZ",
      "is_valid": true,
      "description": "Valid private-use country code (user assignment ZZ)."
    },
    {
      "value": "QA",
      "is_valid": false,
      "description": "Invalid because QA is not allocated and falls outside the private-use QM-QZ range."
    },
    {
      "value": "XX",
      "is_valid": false,
      "description": "Invalid country code (not allocated and outside private-use ranges)."
    },
    {
      "value": "USA",
      "is_valid": false,
      "description": "Invalid because ISO 3166-1 alpha-2 codes consist of exactly two letters."
    }
  ],
  "resources": [
    {
      "url": "https://www.iso.org/iso-3166-country-codes.html",
      "title": "ISO 3166 Country Codes",
      "description": "Official ISO portal for the country code standard (ISO 3166).",
      "publisher": "International Organization for Standardization"
    },
    {
      "url": "https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2",
      "title": "ISO 3166-1 Alpha-2 (Wikipedia)",
      "description": "Wikipedia article detailing the two-letter country codes defined in the ISO 3166-1 standard."
    }
  ],
  "meta": {
    "relativePath": "global/iso3166-2_codes.yaml",
    "category": "global",
    "key": "iso3166-2_codes",
    "slug": "global-iso3166-2_codes",
    "filePath": "library/global/iso3166-2_codes.yaml"
  }
}