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
          def validate_ssn(val: str) -> bool:
              if not re.match(r"^\d{3}-\d{2}-\d{4}$", val):
                  return False
              area, group, serial = val.split("-")
              return (
                  area not in ("000", "666") and
                  not area.startswith("9") and
                  group != "00" and
                  serial != "0000"
              )
      - 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.