Canadian Postal Code

{
  "id": "https://w3id.org/dartfx/semanticdt/library/ca/postal_code",
  "name": "Canadian Postal Code",
  "description": "A six-character alphanumeric string that forms part of a postal address in Canada. It is formatted as A1A 1A1, where A is a letter and 1 is a digit, separated by a space.",
  "version": "0.1.0",
  "concepts": [
    {
      "uri": "https://www.wikidata.org/wiki/Q1478124",
      "vocabulary": "Wikidata",
      "pref_label": "postal codes in Canada",
      "match_type": "exactMatch"
    }
  ],
  "storage_types": [
    {
      "target_environment": "generic",
      "data_type": "string"
    },
    {
      "target_environment": "python",
      "data_type": "str"
    },
    {
      "target_environment": "sql",
      "data_type": "VARCHAR",
      "format_modifier": 7
    },
    {
      "target_environment": "xsd",
      "data_type": "string"
    }
  ],
  "validation_rules": [
    {
      "rule_type": "regex",
      "pattern": "^[ABCEGHJKLMNPRSTVXY]\\d[ABCEGHJKLMNPRSTVWXYZ] ?\\d[ABCEGHJKLMNPRSTVWXYZ]\\d$",
      "message": "Canadian Postal Code must be formatted as A1A 1A1 or A1A1A1 (case-insensitive)."
    },
    {
      "rule_type": "custom",
      "message": "Canadian Postal Code failed format or character validation.",
      "code_snippets": [
        {
          "target_environment": "python",
          "code": "import re\ndef validate_postal_code(val: str) -> bool:\n    return bool(re.match(r\"^[ABCEGHJKLMNPRSTVXY]\\d[ABCEGHJKLMNPRSTVWXYZ] ?\\d[ABCEGHJKLMNPRSTVWXYZ]\\d$\", val, re.IGNORECASE))\n"
        },
        {
          "target_environment": "sql",
          "code": "UPPER(val) ~ '^[ABCEGHJKLMNPRSTVXY][0-9][ABCEGHJKLMNPRSTVWXYZ] ?[0-9][ABCEGHJKLMNPRSTVWXYZ][0-9]$'"
        }
      ]
    }
  ],
  "generation_rules": [
    {
      "generator_type": "regex_fuzzer",
      "template": "^[ABCEGHJKLMNPRSTVXY][0-9][ABCEGHJKLMNPRSTVWXYZ] [0-9][ABCEGHJKLMNPRSTVWXYZ][0-9]$"
    }
  ],
  "agent_instructions": {
    "guidelines": "Canadian Postal Codes use alternating letters and digits in the form A1A 1A1. The letters D, F, I, O, Q, and U are never used. The first letter is never W or Z. Normalize values by converting to uppercase and ensuring a single space separating the FSA and LDU parts (e.g., 'k1a0b1' -> 'K1A 0B1').",
    "system_prompt_snippet": "Ensure Canadian Postal Codes are normalized to uppercase with a single space (e.g., 'K1A 0B1') before processing."
  },
  "scope": {
    "geospatial_coverage": {
      "description": "Canada",
      "codes": [
        "CA",
        "ISO-3166-1:CA",
        "https://www.wikidata.org/wiki/Q16"
      ]
    },
    "domain": "Geographic",
    "governing_institution": "Canada Post"
  },
  "display_format": {
    "input_mask": "A1A 1A1",
    "display_template": "{{ value.upper() }}"
  },
  "examples": [
    {
      "value": "K1A 0B1",
      "is_valid": true,
      "description": "A standard valid Canadian postal code (Canada Post headquarters)."
    },
    {
      "value": "M5V 2T6",
      "is_valid": true,
      "description": "A standard valid Canadian postal code."
    },
    {
      "value": "H0H 0H0",
      "is_valid": true,
      "description": "Santa Claus's postal code."
    },
    {
      "value": "k1a0b1",
      "is_valid": true,
      "description": "A valid Canadian postal code in lowercase and without space."
    },
    {
      "value": "K1A 0D1",
      "is_valid": false,
      "description": "Invalid because it contains the forbidden letter 'D'."
    },
    {
      "value": "W1A 0B1",
      "is_valid": false,
      "description": "Invalid because the first letter is 'W'."
    },
    {
      "value": "K1A-0B1",
      "is_valid": false,
      "description": "Invalid because it uses a hyphen separator instead of a space."
    },
    {
      "value": "1A1 A1A",
      "is_valid": false,
      "description": "Invalid because the character positions are reversed."
    }
  ],
  "resources": [
    {
      "url": "https://www.canadapost-postescanada.ca/cpc/en/tools/find-a-postal-code.page",
      "title": "Canada Post Find a Postal Code",
      "description": "Official Canada Post tool to look up and verify postal codes.",
      "publisher": "Canada Post"
    },
    {
      "url": "https://en.wikipedia.org/wiki/Postal_codes_in_Canada",
      "title": "Postal Codes in Canada (Wikipedia)",
      "description": "Wikipedia article detailing the history, FSA, LDU, and routing of Canadian postal codes."
    }
  ],
  "meta": {
    "relativePath": "ca/postal_code.yaml",
    "category": "ca",
    "key": "postal_code",
    "slug": "ca-postal_code",
    "filePath": "library/ca/postal_code.yaml"
  }
}