{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/breaches/refs/heads/main/json-schema/breaches-exposed-credential-schema.json",
  "title": "ExposedCredential",
  "description": "An individual credential exposure record linking a subject identifier (email, username, phone, or password hash) to one or more breach sources, with metadata about freshness and provenance.",
  "type": "object",
  "properties": {
    "subject_type": {
      "type": "string",
      "description": "The kind of identifier this exposure pertains to.",
      "enum": ["email", "username", "phone", "domain", "password-hash", "session-cookie", "ip-address"],
      "example": "email"
    },
    "subject_value": {
      "type": "string",
      "description": "The identifier value being checked. For password-hash subjects this is typically a SHA-1 prefix to support k-anonymity.",
      "example": "user@example.com"
    },
    "exposed": {
      "type": "boolean",
      "description": "Whether the subject was found in one or more breach datasets.",
      "example": true
    },
    "exposure_count": {
      "type": "integer",
      "minimum": 0,
      "description": "Number of distinct breach sources in which the subject appears.",
      "example": 7
    },
    "first_seen": {
      "type": "string",
      "format": "date-time",
      "description": "Earliest known appearance of the credential exposure.",
      "example": "2013-12-04T00:00:00Z"
    },
    "last_seen": {
      "type": "string",
      "format": "date-time",
      "description": "Most recent appearance of the credential exposure.",
      "example": "2025-11-12T08:14:00Z"
    },
    "breach_sources": {
      "type": "array",
      "description": "Breach records in which the subject was found.",
      "items": {
        "type": "object",
        "properties": {
          "breach_name": { "type": "string", "example": "Adobe" },
          "breach_date": { "type": "string", "format": "date", "example": "2013-10-04" },
          "data_classes": {
            "type": "array",
            "items": { "type": "string" },
            "example": ["Email addresses", "Passwords"]
          }
        },
        "required": ["breach_name"]
      }
    },
    "stealer_log_hits": {
      "type": "integer",
      "minimum": 0,
      "description": "Number of distinct infostealer log entries the subject appears in.",
      "example": 2
    },
    "password_strength": {
      "type": "string",
      "description": "Qualitative strength assessment when the underlying password is known.",
      "enum": ["unknown", "very-weak", "weak", "moderate", "strong", "very-strong"],
      "example": "weak"
    },
    "risk_level": {
      "type": "string",
      "description": "Aggregate exposure risk derived from recency, breach severity, and data classes.",
      "enum": ["informational", "low", "medium", "high", "critical"],
      "example": "high"
    },
    "k_anonymity": {
      "type": "object",
      "description": "K-anonymity envelope used when querying by password hash prefix.",
      "properties": {
        "hash_prefix": {
          "type": "string",
          "description": "First N characters of the password hash submitted.",
          "example": "21BD1"
        },
        "hash_algorithm": {
          "type": "string",
          "enum": ["sha1", "ntlm", "sha256"],
          "example": "sha1"
        }
      }
    },
    "recommended_action": {
      "type": "string",
      "description": "Operational guidance for the consumer of this record.",
      "enum": ["no-action", "monitor", "notify-user", "force-password-reset", "revoke-session", "step-up-auth"],
      "example": "force-password-reset"
    }
  },
  "required": ["subject_type", "subject_value", "exposed"]
}