US Social Security Number

{
  "id": "https://w3id.org/dartfx/semanticdt/library/us/ssn",
  "name": "US Social Security Number",
  "description": "A 9-digit number issued to U.S. citizens, permanent residents, and temporary (working) residents to track individuals for taxation and social security purposes.",
  "version": "0.1.0",
  "concepts": [
    {
      "uri": "https://www.wikidata.org/wiki/Q5612679",
      "vocabulary": "Wikidata",
      "pref_label": "Social Security number (United States)",
      "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": 11
    },
    {
      "target_environment": "xsd",
      "data_type": "string"
    }
  ],
  "validation_rules": [
    {
      "rule_type": "regex",
      "pattern": "^\\d{3}-\\d{2}-\\d{4}$",
      "message": "SSN must be formatted as 999-99-9999."
    },
    {
      "rule_type": "regex",
      "pattern": "^(?!000|666|9\\d{2})\\d{3}-(?!00)\\d{2}-(?!0000)\\d{4}$",
      "message": "SSN contains invalid area (000, 666, 900-999), group (00), or serial (0000) number ranges."
    },
    {
      "rule_type": "custom",
      "message": "SSN failed programmatic integrity check.",
      "code_snippets": [
        {
          "target_environment": "python",
          "code": "import re\ndef validate_ssn(val: str) -> bool:\n    if not re.match(r\"^\\d{3}-\\d{2}-\\d{4}$\", val):\n        return False\n    area, group, serial = val.split(\"-\")\n    return (\n        area not in (\"000\", \"666\") and\n        not area.startswith(\"9\") and\n        group != \"00\" and\n        serial != \"0000\"\n    )\n"
        },
        {
          "target_environment": "sql",
          "code": "val ~ '^\\d{3}-\\d{2}-\\d{4}$' AND SUBSTRING(val, 1, 3) NOT IN ('000', '666') AND SUBSTRING(val, 1, 1) <> '9' AND SUBSTRING(val, 5, 2) <> '00' AND SUBSTRING(val, 8, 4) <> '0000'"
        }
      ]
    }
  ],
  "generation_rules": [
    {
      "generator_type": "regex_fuzzer",
      "template": "^[0-8][0-9]{2}-[0-9]{2}-[0-9]{4}$"
    }
  ],
  "agent_instructions": {
    "guidelines": "U.S. Social Security Numbers are highly sensitive Personally Identifiable Information (PII). Treat them with high security. Never log, store, or output them in plaintext. Mask them wherever possible to the last 4 digits (e.g., XXX-XX-6789).",
    "system_prompt_snippet": "This variable contains a U.S. Social Security Number. Treat as confidential PII. Redact or mask the first 5 digits when displaying to users or logging."
  },
  "scope": {
    "geospatial_coverage": {
      "description": "United States of America",
      "codes": [
        "US",
        "ISO-3166-1:US",
        "https://www.wikidata.org/wiki/Q30"
      ]
    },
    "domain": "Demographic",
    "governing_institution": "Social Security Administration"
  },
  "display_format": {
    "input_mask": "999-99-9999",
    "display_template": "XXX-XX-{{ value[-4:] }}"
  },
  "examples": [
    {
      "value": "123-45-6789",
      "is_valid": true,
      "description": "A standard valid U.S. Social Security Number."
    },
    {
      "value": "000-12-3456",
      "is_valid": false,
      "description": "Invalid because area number 000 is not allocated."
    },
    {
      "value": "666-23-4567",
      "is_valid": false,
      "description": "Invalid because area number 666 is excluded."
    },
    {
      "value": "123-00-6789",
      "is_valid": false,
      "description": "Invalid because group number 00 is invalid."
    },
    {
      "value": "123-45-0000",
      "is_valid": false,
      "description": "Invalid because serial number 0000 is invalid."
    },
    {
      "value": 123456789,
      "is_valid": false,
      "description": "Invalid because it lacks the required hyphen formatting."
    }
  ],
  "resources": [
    {
      "url": "https://en.wikipedia.org/wiki/Social_Security_number",
      "title": "Social Security Number (Wikipedia)",
      "description": "Wikipedia article detailing the history, issuance, structure, and security concerns of United States Social Security Numbers."
    }
  ],
  "meta": {
    "relativePath": "us/ssn.yaml",
    "category": "us",
    "key": "ssn",
    "slug": "us-ssn",
    "filePath": "library/us/ssn.yaml"
  }
}