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
          def validate_postal_code(val: str) -> bool:
              return bool(re.match(r"^[ABCEGHJKLMNPRSTVXY]\d[ABCEGHJKLMNPRSTVWXYZ] ?\d[ABCEGHJKLMNPRSTVWXYZ]\d$", val, re.IGNORECASE))
      - 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.