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:
              clean = val.strip().upper()
              if clean in {"AA", "ZZ"}:
                  return True
              if len(clean) == 2:
                  if clean[0] == 'Q' and 'M' <= clean[1] <= 'Z':
                      return True
                  if clean[0] == 'X' and 'A' <= clean[1] <= 'Z':
                      return True
              valid_codes = {
                  "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ",
                  "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS",
                  "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN",
                  "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE",
                  "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF",
                  "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM",
                  "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM",
                  "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC",
                  "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK",
                  "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA",
                  "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG",
                  "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW",
                  "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS",
                  "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO",
                  "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI",
                  "VN", "VU", "WF", "WS", "YE", "YT", "ZA", "ZM", "ZW"
              }
              return clean in valid_codes
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.