US ZIP Code

{
  "id": "https://w3id.org/dartfx/semanticdt/library/us/zip_code",
  "name": "US ZIP Code",
  "description": "A ZIP Code is a postal code used by the United States Postal Service (USPS). It can be either the basic 5-digit format or the extended 9-digit ZIP+4 format.",
  "version": "0.1.0",
  "concepts": [
    {
      "uri": "https://www.wikidata.org/wiki/Q136208",
      "vocabulary": "Wikidata",
      "pref_label": "ZIP Code",
      "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": 10
    },
    {
      "target_environment": "xsd",
      "data_type": "string"
    }
  ],
  "validation_rules": [
    {
      "rule_type": "regex",
      "pattern": "^\\d{5}(-\\d{4})?$",
      "message": "US ZIP Code must be formatted as 99999 or 99999-9999."
    },
    {
      "rule_type": "custom",
      "message": "US ZIP Code failed format check.",
      "code_snippets": [
        {
          "target_environment": "python",
          "code": "import re\ndef validate_zip(val: str) -> bool:\n    return bool(re.match(r\"^\\d{5}(-\\d{4})?$\", val))\n"
        },
        {
          "target_environment": "sql",
          "code": "val ~ '^\\d{5}(-\\d{4})?$'"
        }
      ]
    }
  ],
  "generation_rules": [
    {
      "generator_type": "regex_fuzzer",
      "template": "^[0-9]{5}(-[0-9]{4})?$"
    }
  ],
  "agent_instructions": {
    "guidelines": "U.S. ZIP Codes contain leading zeros which are significant (e.g., '02138'). Always preserve the type as string. Do not convert to numerical/integer representation.",
    "system_prompt_snippet": "Treat US ZIP Code variables as strings to prevent loss of leading zeros. Validate against standard 5-digit or 9-digit ZIP+4 patterns."
  },
  "scope": {
    "geospatial_coverage": {
      "description": "United States of America",
      "codes": [
        "US",
        "ISO-3166-1:US",
        "https://www.wikidata.org/wiki/Q30"
      ]
    },
    "domain": "Geographic",
    "governing_institution": "United States Postal Service"
  },
  "display_format": {
    "input_mask": "99999-9999",
    "display_template": "{{ value }}"
  },
  "examples": [
    {
      "value": "90210",
      "is_valid": true,
      "description": "A standard 5-digit valid ZIP code."
    },
    {
      "value": "12345-6789",
      "is_valid": true,
      "description": "A standard 9-digit valid ZIP+4 code."
    },
    {
      "value": "02138",
      "is_valid": true,
      "description": "A valid 5-digit ZIP code with a leading zero."
    },
    {
      "value": "1234",
      "is_valid": false,
      "description": "Invalid because it is too short."
    },
    {
      "value": "123456",
      "is_valid": false,
      "description": "Invalid because it has too many digits."
    },
    {
      "value": "abcde",
      "is_valid": false,
      "description": "Invalid because it contains alphabetic characters."
    }
  ],
  "resources": [
    {
      "url": "https://pe.usps.com/",
      "title": "USPS Postal Explorer",
      "description": "Official United States Postal Service domestic mail manual and addressing standards.",
      "citation": "United States Postal Service. (2026). Postal Explorer. Retrieved from https://pe.usps.com/"
    },
    {
      "url": "https://en.wikipedia.org/wiki/ZIP_Code",
      "title": "ZIP Code (Wikipedia)",
      "description": "Wikipedia article detailing the history, structure, and usage of United States ZIP codes."
    }
  ],
  "meta": {
    "relativePath": "us/zip_code.yaml",
    "category": "us",
    "key": "zip_code",
    "slug": "us-zip_code",
    "filePath": "library/us/zip_code.yaml"
  }
}