VerdictResult

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/farofinance-app/json-schema/farofinance-app-verdict-result-schema.json",
  "title": "VerdictResult",
  "description": "The single verdict object returned by every verify endpoint and SDK method.",
  "x-generated": "2026-11-08",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/_original/farofinance-app-api-openapi.json#/components/schemas/VerdictResult",
  "properties": {
    "verdict": {
      "$ref": "#/$defs/Verdict",
      "description": "Traffic-light verdict: green, yellow, or red."
    },
    "confidence": {
      "type": "number",
      "maximum": 1.0,
      "minimum": 0.0,
      "title": "Confidence",
      "description": "Calibrated confidence in the verdict (honest about data completeness)."
    },
    "artifact": {
      "$ref": "#/$defs/Artifact"
    },
    "reason": {
      "type": "string",
      "title": "Reason",
      "description": "One plain-language line explaining the verdict — always present."
    },
    "recommended_action": {
      "$ref": "#/$defs/Action",
      "description": "What to do next: allow, warn, block, or review."
    },
    "signals": {
      "items": {
        "$ref": "#/$defs/Signal"
      },
      "type": "array",
      "title": "Signals",
      "description": "Evidence behind the verdict — deterministic checks, enrichment, reputation."
    },
    "explanation": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Explanation",
      "description": "Optional longer context (e.g. session repeat-check notes)."
    },
    "request_id": {
      "type": "string",
      "title": "Request Id",
      "description": "Unique id for this request (also in the `X-Request-ID` response header)."
    },
    "cached": {
      "type": "boolean",
      "title": "Cached",
      "description": "True when served from the verdict cache (`X-Faro-Cache: hit`).",
      "default": false
    },
    "first_seen": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ],
      "title": "First Seen",
      "description": "When Faro first saw this normalized node in the reputation graph."
    },
    "checked_at": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ],
      "title": "Checked At",
      "description": "When this verdict was computed."
    }
  },
  "type": "object",
  "required": [
    "verdict",
    "confidence",
    "artifact",
    "reason",
    "recommended_action",
    "request_id"
  ],
  "$defs": {
    "Action": {
      "type": "string",
      "enum": [
        "allow",
        "warn",
        "block",
        "review"
      ],
      "title": "Action"
    },
    "Artifact": {
      "properties": {
        "type": {
          "$ref": "#/$defs/ArtifactType",
          "description": "The kind of artifact that was verified."
        },
        "value": {
          "type": "string",
          "title": "Value",
          "description": "The normalized artifact string that was checked."
        }
      },
      "type": "object",
      "required": [
        "type",
        "value"
      ],
      "title": "Artifact"
    },
    "ArtifactType": {
      "type": "string",
      "enum": [
        "url",
        "payee",
        "message",
        "document"
      ],
      "title": "ArtifactType"
    },
    "Severity": {
      "type": "string",
      "enum": [
        "info",
        "low",
        "medium",
        "high",
        "critical"
      ],
      "title": "Severity"
    },
    "Signal": {
      "properties": {
        "name": {
          "type": "string",
          "title": "Name",
          "description": "Machine-readable signal id, e.g. `domain_age_days`."
        },
        "severity": {
          "$ref": "#/$defs/Severity",
          "description": "How strongly this signal affects the verdict."
        },
        "detail": {
          "type": "string",
          "title": "Detail",
          "description": "Human-readable explanation of what was found."
        },
        "source": {
          "type": "string",
          "title": "Source",
          "description": "Integration that produced the signal, e.g. `safe_browsing`."
        }
      },
      "type": "object",
      "required": [
        "name",
        "severity",
        "detail",
        "source"
      ],
      "title": "Signal"
    },
    "Verdict": {
      "type": "string",
      "enum": [
        "green",
        "yellow",
        "red"
      ],
      "title": "Verdict"
    }
  }
}