{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://geosonar.ai/schema/geo-audit-result/v1.0.0",
  "title": "GEO Audit Result",
  "description": "Schema for Generative Engine Optimization audit results, including scores, findings, citation tests, source references, GEO methods, SERP impact, platform readiness, and prioritized actions.",
  "type": "object",
  "required": ["$schema", "version", "tool", "run", "target", "scores", "categories"],
  "properties": {
    "$schema": {
      "type": "string",
      "const": "https://geosonar.ai/schema/geo-audit-result/v1.0.0",
      "description": "Schema URI for validation and version identification."
    },
    "version": {
      "type": "string",
      "const": "1.0.0",
      "description": "Schema version following semver."
    },
    "tool": {
      "type": "object",
      "description": "Identity of the tool that produced this result (SARIF: tool).",
      "required": ["name", "version"],
      "properties": {
        "name": {
          "type": "string",
          "description": "Tool name."
        },
        "version": {
          "type": "string",
          "description": "Tool version (semver).",
          "examples": ["1.0.0"]
        },
        "informationUri": {
          "type": "string",
          "format": "uri",
          "description": "URL for tool documentation."
        },
        "rules": {
          "type": "array",
          "description": "Registry of all issue types the tool can report (SARIF: reportingDescriptor).",
          "items": { "$ref": "#/$defs/Rule" }
        }
      }
    },

    "run": {
      "type": "object",
      "description": "Metadata about this specific audit execution (SARIF: run).",
      "required": ["id", "timestamp"],
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid",
          "description": "Unique run identifier."
        },
        "timestamp": {
          "type": "string",
          "format": "date-time",
          "description": "ISO 8601 start time."
        },
        "completedAt": {
          "type": "string",
          "format": "date-time",
          "description": "ISO 8601 completion time."
        },
        "durationMs": {
          "type": "integer",
          "minimum": 0,
          "description": "Total execution time in milliseconds."
        },
        "status": {
          "type": "string",
          "enum": ["pending", "running", "completed", "failed"],
          "description": "Run status."
        },
        "triggerType": {
          "type": "string",
          "enum": ["manual", "scheduled", "webhook", "ci"],
          "description": "What initiated this audit."
        },
        "scope": {
          "type": "string",
          "enum": ["full-site", "single-page", "quick"],
          "description": "Audit scope."
        },
        "pagesAnalyzed": {
          "type": "integer",
          "minimum": 0,
          "description": "Number of pages crawled."
        },
        "phases": {
          "type": "array",
          "description": "Pipeline phases executed in this run.",
          "items": {
            "type": "string",
            "enum": [
              "context-detection",
              "technical-audit",
              "keyword-analysis",
              "citation-tests",
              "social-presence",
              "scoring",
              "insight-generation",
              "report-generation"
            ]
          }
        },
        "configuration": {
          "type": "object",
          "description": "Runtime parameters that affect results.",
          "properties": {
            "maxPages": { "type": "integer" },
            "fetchTimeoutSeconds": { "type": "integer" },
            "rateLimitDelaySeconds": { "type": "number" },
            "maxConcurrent": { "type": "integer" },
            "enabledEngines": {
              "type": "array",
              "items": { "$ref": "#/$defs/EngineId" },
              "description": "AI engines enabled for citation testing."
            },
            "enabledPlatforms": {
              "type": "array",
              "items": { "$ref": "#/$defs/PlatformId" },
              "description": "Social/review platforms enabled for presence checks."
            },
            "blueprint": {
              "type": "string",
              "description": "Business vertical used for weight overrides.",
              "enum": ["saas", "ecommerce", "services", "b2c", "enterprise", "publisher", "agency", "local-service"]
            },
            "weights": { "$ref": "#/$defs/ResolvedWeights" },
            "configVersion": {
              "type": "object",
              "description": "Identifies the exact scoring configuration that produced this result.",
              "properties": {
                "formula": {
                  "type": "string",
                  "description": "Formula file name (e.g., 'v1', 'v2', 'v3-experimental')."
                },
                "blueprint": {
                  "type": ["string", "null"],
                  "description": "Blueprint applied, or null for defaults."
                },
                "hash": {
                  "type": "string",
                  "description": "Short git SHA of config/ directory at run time."
                }
              }
            }
          }
        }
      }
    },

    "target": {
      "type": "object",
      "description": "The website or page being audited (Schema.org: WebSite / WebPage).",
      "required": ["url"],
      "properties": {
        "url": {
          "type": "string",
          "format": "uri",
          "description": "Canonical URL of the audit target."
        },
        "name": {
          "type": "string",
          "description": "Brand or organization name (Schema.org: name)."
        },
        "description": {
          "type": "string",
          "description": "Site meta description."
        },
        "businessType": {
          "type": "string",
          "enum": ["saas", "ecommerce", "services", "b2c", "enterprise", "publisher", "agency", "local-service", "other"],
          "description": "Detected or configured business vertical."
        },
        "language": {
          "type": "string",
          "description": "Primary content language (BCP 47).",
          "examples": ["en", "it", "de"]
        },
        "domain": {
          "type": "string",
          "description": "Root domain without protocol.",
          "examples": ["geosonar.ai"]
        },
        "sameAs": {
          "type": "array",
          "items": { "type": "string", "format": "uri" },
          "description": "Known social/platform profile URLs (Schema.org: sameAs)."
        }
      }
    },

    "scores": {
      "type": "object",
      "description": "Top-level composite scores. Contains the overall score plus pillar/category scores.",
      "required": ["overall"],
      "properties": {
        "overall": { "$ref": "#/$defs/Score" },
        "visibility": { "$ref": "#/$defs/Score" },
        "infrastructure": { "$ref": "#/$defs/Score" },
        "narrative": { "$ref": "#/$defs/Score" },
        "authority": { "$ref": "#/$defs/Score" }
      },
      "additionalProperties": { "$ref": "#/$defs/Score" }
    },

    "categories": {
      "type": "array",
      "description": "Detailed category/pillar results with sub-metric audits (Lighthouse: categories + audits).",
      "items": { "$ref": "#/$defs/Category" }
    },

    "findings": {
      "type": "array",
      "description": "Individual issue instances across all categories (SARIF: results).",
      "items": { "$ref": "#/$defs/Finding" }
    },

    "insights": {
      "type": "array",
      "description": "Strategic recommendations with root cause analysis.",
      "items": { "$ref": "#/$defs/Insight" }
    },

    "citationTests": {
      "type": "object",
      "description": "Citation test results by AI engine.",
      "properties": {
        "results": {
          "type": "array",
          "items": { "$ref": "#/$defs/CitationTestResult" }
        },
        "summary": {
          "type": "object",
          "description": "Aggregate citation counts.",
          "properties": {
            "totalTests": { "type": "integer", "minimum": 0 },
            "totalCited": { "type": "integer", "minimum": 0 },
            "citationRate": {
              "type": "number",
              "minimum": 0,
              "maximum": 1,
              "description": "Fraction of tests where target was cited (0-1)."
            },
            "stabilityIndex": {
              "type": ["number", "null"],
              "minimum": 0,
              "maximum": 100,
              "description": "Citation rate consistency across scans (0-100). A value of 100 indicates no observed variation. Null when only one scan is available."
            },
            "perEngine": {
              "type": "object",
              "description": "Citation count per engine.",
              "additionalProperties": {
                "type": "object",
                "properties": {
                  "tested": { "type": "integer" },
                  "cited": { "type": "integer" }
                }
              }
            },
            "perQueryType": {
              "type": "object",
              "description": "Citation count per query type.",
              "additionalProperties": {
                "type": "object",
                "properties": {
                  "tested": { "type": "integer" },
                  "cited": { "type": "integer" }
                }
              }
            }
          }
        }
      }
    },

    "citationNetwork": {
      "type": "array",
      "description": "Source domains cited by AI engines across the competitive citation landscape.",
      "items": { "$ref": "#/$defs/CitationNetworkEntry" }
    },

    "competingBrands": {
      "type": "array",
      "description": "Brands that appear in AI responses for discovery queries targeting the same space.",
      "items": { "$ref": "#/$defs/CompetingBrand" }
    },

    "geoMethods": {
      "type": "object",
      "description": "GEO method audit results for the supported optimization methods.",
      "properties": {
        "aggregateScore": {
          "type": "integer",
          "minimum": 0,
          "maximum": 100,
          "description": "Weighted average across all methods."
        },
        "methodCount": {
          "type": "integer",
          "description": "Number of methods with passing scores."
        },
        "totalMethods": {
          "type": "integer",
          "description": "Total methods evaluated."
        },
        "methods": {
          "type": "object",
          "description": "Per-method scores with evidence.",
          "additionalProperties": { "$ref": "#/$defs/GeoMethodResult" }
        }
      }
    },

    "serpImpact": {
      "type": "object",
      "description": "SERP-position-aware GEO method impact analysis for prioritizing optimization methods.",
      "properties": {
        "serpPosition": {
          "type": ["integer", "null"],
          "description": "Current organic SERP position for primary keyword, or null if not ranked."
        },
        "rankTier": {
          "type": "string",
          "enum": ["high", "mid", "low", "not-ranked", "unknown"],
          "description": "Position tier: high (1-10), mid (11-30), low (31+), not-ranked, unknown."
        },
        "impactLevel": {
          "type": "string",
          "enum": ["low", "medium", "high", "unknown"],
          "description": "Estimated impact of GEO optimization at this rank tier."
        },
        "impactSummary": {
          "type": "string",
          "description": "Human-readable summary of SERP impact assessment."
        },
        "methodRecommendations": {
          "type": "array",
          "description": "GEO methods sorted by adjusted impact for this rank tier.",
          "items": { "$ref": "#/$defs/MethodRecommendation" }
        }
      }
    },

    "socialPresence": {
      "type": "object",
      "description": "Brand presence verification across social and review platforms.",
      "properties": {
        "results": {
          "type": "array",
          "items": { "$ref": "#/$defs/SocialPresenceResult" }
        },
        "verifiedCount": {
          "type": "integer",
          "minimum": 0,
          "description": "Number of platforms where brand presence was verified."
        },
        "totalChecked": {
          "type": "integer",
          "minimum": 0,
          "description": "Total platforms checked."
        }
      }
    },

    "crawlerAccess": {
      "type": "object",
      "description": "AI crawler access status from robots.txt analysis.",
      "additionalProperties": { "$ref": "#/$defs/CrawlerStatus" }
    },

    "platformReadiness": {
      "type": "object",
      "description": "Per-platform AI visibility readiness scores.",
      "additionalProperties": { "$ref": "#/$defs/Score" }
    },

    "actionPlan": {
      "type": "object",
      "description": "Prioritized remediation actions grouped by time horizon.",
      "properties": {
        "quickWins": {
          "type": "array",
          "items": { "$ref": "#/$defs/Action" },
          "description": "Actions estimated to take less than one week with high expected impact."
        },
        "mediumTerm": {
          "type": "array",
          "items": { "$ref": "#/$defs/Action" },
          "description": "Moderate-effort improvements (1-4 weeks)."
        },
        "strategic": {
          "type": "array",
          "items": { "$ref": "#/$defs/Action" },
          "description": "Long-term initiatives (1-3 months)."
        }
      }
    },

    "executiveSummary": {
      "type": "string",
      "description": "Human-readable summary of audit findings (4-6 sentences)."
    },

    "citationGraphMetrics": {
      "type": "object",
      "description": "Citation network graph metrics (PageRank per domain, co-citation clusters).",
      "additionalProperties": true
    }
  },

  "$defs": {

    "EngineId": {
      "type": "string",
      "enum": ["perplexity", "chatgpt", "gemini", "claude", "copilot"],
      "description": "AI engine identifier."
    },

    "PlatformId": {
      "type": "string",
      "enum": ["twitter", "reddit", "producthunt", "g2", "capterra", "trustpilot", "trustradius", "youtube", "linkedin", "wikipedia", "github", "quora", "stackoverflow", "crunchbase"],
      "description": "Social or review platform identifier."
    },

    "QueryType": {
      "type": "string",
      "enum": [
        "brand-direct",
        "brand-review",
        "discovery-specific",
        "discovery-generic",
        "discovery-intent"
      ],
      "description": "Citation test query type. Branded queries test name recognition; discovery queries test unbranded category visibility."
    },

    "DataSource": {
      "type": "string",
      "enum": ["crawler", "api", "search-api", "citation-test", "manual", "llm"],
      "description": "What tool or method produced a given data point."
    },

    "Score": {
      "type": "object",
      "description": "A normalized score with label and display metadata (Lighthouse: score pattern).",
      "required": ["value", "maxValue"],
      "properties": {
        "value": {
          "type": "number",
          "minimum": 0,
          "description": "Numeric score."
        },
        "maxValue": {
          "type": "number",
          "minimum": 0,
          "description": "Scale maximum (typically 100).",
          "default": 100
        },
        "label": {
          "type": "string",
          "enum": ["excellent", "good", "fair", "poor", "critical"],
          "description": "Qualitative label derived from thresholds."
        },
        "displayValue": {
          "type": "string",
          "description": "Formatted string for display.",
          "examples": ["68 / 100", "Good"]
        },
        "weight": {
          "type": "number",
          "minimum": 0,
          "maximum": 1,
          "description": "Weight in composite score (0-1, sum of sibling weights = 1)."
        }
      }
    },

    "ResolvedWeights": {
      "type": "object",
      "description": "Resolved scoring weights after configured overrides, normalized to sum to 1.0 per level.",
      "properties": {
        "blueprint": {
          "type": ["string", "null"],
          "description": "Blueprint that was applied, or null for defaults."
        },
        "pillar": {
          "type": "object",
          "description": "Pillar-level weights (must sum to 1.0).",
          "additionalProperties": { "type": "number" }
        },
        "infrastructure": {
          "type": "object",
          "description": "Sub-metric weights within infrastructure (must sum to 1.0).",
          "additionalProperties": { "type": "number" }
        },
        "narrative": {
          "type": "object",
          "description": "Sub-metric weights within narrative (must sum to 1.0).",
          "additionalProperties": { "type": "number" }
        },
        "authority": {
          "type": "object",
          "description": "Sub-metric weights within authority (must sum to 1.0).",
          "additionalProperties": { "type": "number" }
        }
      }
    },

    "Category": {
      "type": "object",
      "description": "A scoring category (pillar) containing related sub-metric audits (Lighthouse: category).",
      "required": ["id", "title", "score"],
      "properties": {
        "id": {
          "type": "string",
          "description": "Machine-readable category identifier (kebab-case).",
          "examples": ["infrastructure", "narrative", "authority", "visibility"]
        },
        "title": {
          "type": "string",
          "description": "Human-readable category name."
        },
        "description": {
          "type": "string",
          "description": "What this category measures."
        },
        "score": { "$ref": "#/$defs/Score" },
        "audits": {
          "type": "array",
          "description": "Individual sub-metric audit checks within this category.",
          "items": { "$ref": "#/$defs/Audit" }
        }
      }
    },

    "Audit": {
      "type": "object",
      "description": "A single sub-metric audit check (Lighthouse: audit).",
      "required": ["id", "title", "score"],
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique audit identifier (kebab-case).",
          "examples": [
            "structural-presence", "technical-accessibility", "structured-data",
            "crawlability", "site-architecture",
            "completeness", "coherence",
            "semantic-alignment", "factual-density", "geo-method-score",
            "external-mentions", "reviews-rating", "competitive-visibility",
            "backlink-quality", "industry-authority", "discovery-citation-rate"
          ]
        },
        "title": {
          "type": "string",
          "description": "Short human-readable title."
        },
        "description": {
          "type": "string",
          "description": "What this audit checks."
        },
        "score": {
          "type": ["number", "null"],
          "minimum": 0,
          "maximum": 1,
          "description": "Normalized score (0-1) or null if not applicable (Lighthouse convention)."
        },
        "scoreDisplayMode": {
          "type": "string",
          "enum": ["numeric", "binary", "informative", "manual", "not-applicable"],
          "description": "How to interpret and display the score (Lighthouse: scoreDisplayMode)."
        },
        "displayValue": {
          "type": "string",
          "description": "Formatted result string.",
          "examples": ["12 / 14 crawlers allowed", "75 / 100"]
        },
        "dataSource": {
          "$ref": "#/$defs/DataSource",
          "description": "What tool or API produced this score."
        },
        "details": {
          "type": "object",
          "description": "Audit-specific structured details (tables, lists, diagnostics).",
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "table",
                "list",
                "opportunity",
                "diagnostic",
                "debugdata",
                "checklist",
                "grouped",
                "alignment"
              ],
              "description": "Structured detail format hint (Lighthouse: details.type)."
            },
            "items": {
              "type": "array",
              "items": { "type": "object" }
            },
            "headings": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "key": { "type": "string" },
                  "label": { "type": "string" },
                  "valueType": { "type": "string", "enum": ["text", "numeric", "url", "code", "boolean"] }
                }
              }
            }
          }
        }
      }
    },

    "Finding": {
      "type": "object",
      "description": "A single issue or observation (SARIF: result).",
      "required": ["ruleId", "severity", "message"],
      "properties": {
        "ruleId": {
          "type": "string",
          "description": "Reference to a rule in tool.rules (SARIF: ruleId).",
          "examples": ["missing-json-ld", "ai-crawler-blocked", "no-llms-txt", "low-citation-rate"]
        },
        "severity": {
          "type": "string",
          "enum": ["critical", "high", "medium", "low", "info"],
          "description": "Issue severity (SARIF: level mapping — error=critical, warning=high/medium, note=low/info)."
        },
        "category": {
          "type": "string",
          "description": "Parent category id this finding belongs to."
        },
        "pillar": {
          "type": "string",
          "description": "Scoring pillar this finding affects.",
          "enum": ["infrastructure", "narrative", "authority"]
        },
        "message": {
          "type": "object",
          "description": "Human-readable finding description (SARIF: message).",
          "required": ["text"],
          "properties": {
            "text": { "type": "string" },
            "markdown": { "type": "string", "description": "Markdown-formatted version of the message." }
          }
        },
        "occurrences": {
          "type": "array",
          "description": "Concrete manifestations of this finding on specific artifacts/fragments. Each occurrence can have its own severity/impact.",
          "items": { "$ref": "#/$defs/Occurrence" }
        },
        "affectedPageCount": {
          "type": "integer",
          "minimum": 0,
          "description": "Total number of pages affected."
        },
        "recommendation": {
          "type": "string",
          "description": "Actionable fix guidance."
        },
        "effort": {
          "type": "string",
          "enum": ["trivial", "low", "medium", "high"],
          "description": "Estimated implementation effort."
        },
        "impact": {
          "type": "string",
          "enum": ["critical", "high", "medium", "low"],
          "description": "Estimated improvement impact if resolved."
        },
        "engine": {
          "$ref": "#/$defs/EngineId",
          "description": "AI engine this finding relates to, if engine-specific."
        },
        "dataSource": {
          "$ref": "#/$defs/DataSource",
          "description": "What produced this finding."
        }
      }
    },

    "Artifact": {
      "type": "object",
      "description": "Location of an occurrence, including the affected document, file, or page and an optional fragment identifier.",
      "required": ["name"],
      "properties": {
        "name": {
          "type": "string",
          "description": "The document, file, or page affected (SARIF: artifactLocation.uri, W3C: target.source).",
          "examples": ["robots.txt", "/pricing", "homepage", "sitemap.xml"]
        },
        "fragment": {
          "type": ["string", "null"],
          "description": "Specific element within the artifact (SARIF: region, W3C: target.selector). Null when the entire artifact is affected.",
          "examples": ["JSON-LD schema block", "meta description", "H1 heading", "Disallow directives"]
        }
      }
    },

    "Occurrence": {
      "type": "object",
      "description": "Concrete manifestation of a finding on a specific artifact/fragment. Severity/impact at this level because the same rule can be critical on /pricing and low on /terms. Maps to SARIF result.locations[i] with physicalLocation + region.",
      "required": ["artifact"],
      "properties": {
        "artifact": { "$ref": "#/$defs/Artifact" },
        "severity": {
          "type": "string",
          "enum": ["critical", "high", "medium", "low", "info"],
          "description": "Occurrence-specific severity override."
        },
        "impact": {
          "type": "string",
          "enum": ["critical", "high", "medium", "low"],
          "description": "Occurrence-specific impact override."
        },
        "message": {
          "type": "string",
          "description": "Page-specific detail for this occurrence."
        },
        "evidence": {
          "type": "string",
          "description": "Supporting snippet or evidence from the affected page."
        }
      }
    },

    "SourceReference": {
      "type": "object",
      "description": "A URL cited by an AI engine in its response.",
      "required": ["url", "domain"],
      "properties": {
        "url": { "type": "string", "format": "uri", "description": "Full source URL." },
        "domain": { "type": "string", "description": "Extracted domain (without www)." },
        "position": { "type": ["integer", "null"], "description": "Citation position (1-indexed)." }
      }
    },

    "Insight": {
      "type": "object",
      "description": "A strategic recommendation with root cause analysis.",
      "required": ["title", "priority", "pillar", "action"],
      "properties": {
        "title": { "type": "string", "description": "Concise insight title." },
        "priority": {
          "type": "string",
          "enum": ["high", "medium", "low"],
          "description": "Implementation priority."
        },
        "impact": {
          "type": "string",
          "enum": ["high", "medium", "low"],
          "description": "Estimated impact on scores."
        },
        "pillar": {
          "type": "string",
          "description": "Scoring pillar targeted by this insight."
        },
        "rootCause": {
          "type": "string",
          "description": "Why this issue exists."
        },
        "action": {
          "type": "string",
          "description": "Specific remediation action."
        },
        "artifact": {
          "$ref": "#/$defs/Artifact",
          "description": "Primary location where this issue occurs."
        },
        "artifacts": {
          "type": "array",
          "items": { "$ref": "#/$defs/Artifact" },
          "description": "Additional affected locations when the issue spans multiple pages."
        },
        "reason": {
          "type": "string",
          "description": "Why this action will improve GEO performance."
        },
        "engine": {
          "$ref": "#/$defs/EngineId",
          "description": "Specific AI engine this insight targets, if applicable."
        }
      }
    },

    "CitationTestResult": {
      "type": "object",
      "description": "Result from a single AI engine citation test.",
      "required": ["engine", "queryType", "queryText", "cited"],
      "properties": {
        "engine": { "$ref": "#/$defs/EngineId" },
        "queryType": { "$ref": "#/$defs/QueryType" },
        "queryText": {
          "type": "string",
          "description": "The query sent to the AI engine."
        },
        "cited": {
          "type": "boolean",
          "description": "Whether the target brand/domain was mentioned in the response."
        },
        "urlCited": {
          "type": ["boolean", "null"],
          "description": "Whether the target URL was directly linked."
        },
        "position": {
          "type": ["integer", "null"],
          "minimum": 1,
          "description": "Position of the citation in the response (1-indexed), if cited."
        },
        "responseText": {
          "type": ["string", "null"],
          "description": "The AI engine's response text."
        },
        "groundingSources": {
          "type": ["integer", "null"],
          "minimum": 0,
          "description": "Number of grounding/source URLs the engine provided."
        },
        "sourceReferences": {
          "type": "array",
          "items": { "$ref": "#/$defs/SourceReference" },
          "description": "Extracted source URLs from the engine response, with domain and position."
        },
        "modelUsed": {
          "type": ["string", "null"],
          "description": "Specific model or API version used.",
          "examples": ["sonar-pro", "gpt-4.1", "gemini-2.5-flash"]
        },
        "error": {
          "type": ["string", "null"],
          "description": "Error message if the test failed."
        }
      }
    },

    "CitationNetworkEntry": {
      "type": "object",
      "description": "A domain-engine citation pair in the competitive landscape.",
      "required": ["engine", "sourceDomain", "citationCount"],
      "properties": {
        "engine": { "$ref": "#/$defs/EngineId" },
        "sourceDomain": {
          "type": "string",
          "description": "Domain that was cited by the engine."
        },
        "citationCount": {
          "type": "integer",
          "minimum": 1,
          "description": "Number of times this domain was cited."
        },
        "avgPosition": {
          "type": ["number", "null"],
          "description": "Average citation position across queries."
        },
        "queryTypes": {
          "type": "array",
          "items": { "$ref": "#/$defs/QueryType" },
          "description": "Query types that triggered citations of this domain."
        }
      }
    },

    "CompetingBrand": {
      "type": "object",
      "description": "A competing brand that appears in AI responses for discovery queries.",
      "required": ["brand", "domain", "mentionCount"],
      "properties": {
        "brand": {
          "type": "string",
          "description": "Brand name as it appeared in AI responses."
        },
        "domain": {
          "type": "string",
          "description": "Brand's primary domain."
        },
        "mentionCount": {
          "type": "integer",
          "minimum": 1,
          "description": "Total mentions across all engines and queries."
        },
        "engines": {
          "type": "array",
          "items": { "$ref": "#/$defs/EngineId" },
          "description": "Engines that mentioned this brand."
        },
        "queryTypes": {
          "type": "array",
          "items": { "$ref": "#/$defs/QueryType" },
          "description": "Query types that surfaced this brand."
        }
      }
    },

    "GeoMethodResult": {
      "type": "object",
      "description": "Score for a single GEO optimization method.",
      "required": ["score"],
      "properties": {
        "score": {
          "type": "integer",
          "minimum": 0,
          "maximum": 100,
          "description": "Method implementation score (0-100)."
        },
        "found": {
          "type": "array",
          "items": { "type": "string" },
          "description": "Evidence found on the page for this method."
        },
        "missing": {
          "type": "array",
          "items": { "type": "string" },
          "description": "Expected evidence not found."
        }
      }
    },

    "MethodRecommendation": {
      "type": "object",
      "description": "A SERP-position-aware GEO method recommendation with adjusted impact.",
      "required": ["method", "baseBoost", "adjustedImpact"],
      "properties": {
        "method": {
          "type": "string",
          "description": "GEO method identifier.",
          "examples": ["cite-sources", "statistics", "quotations", "authoritative-tone", "technical-terms", "fluency-optimization", "unique-terminology", "easy-to-understand"]
        },
        "label": {
          "type": "string",
          "description": "Human-readable method name.",
          "examples": ["Cite Sources", "Statistics", "Authoritative Tone"]
        },
        "baseBoost": {
          "type": "number",
          "description": "Base impact boost for the method (0-1 scale)."
        },
        "adjustedImpact": {
          "type": "number",
          "description": "Impact adjusted for current SERP position (base * tier multiplier)."
        }
      }
    },

    "SocialPresenceResult": {
      "type": "object",
      "description": "Brand presence check result for a single social or review platform.",
      "required": ["platform", "verified"],
      "properties": {
        "platform": { "$ref": "#/$defs/PlatformId" },
        "verified": {
          "type": "boolean",
          "description": "Whether brand presence was confirmed on this platform."
        },
        "relevance": {
          "type": "integer",
          "minimum": 0,
          "maximum": 100,
          "description": "Relevance score (0-100) — how relevant/active the presence is."
        },
        "url": {
          "type": ["string", "null"],
          "format": "uri",
          "description": "URL of the brand's profile or page on this platform."
        },
        "data": {
          "type": "object",
          "description": "Platform-specific data (followers, ratings, mention counts, etc.).",
          "additionalProperties": true
        },
        "error": {
          "type": ["string", "null"],
          "description": "Error message if the check failed."
        }
      }
    },

    "CrawlerStatus": {
      "type": "object",
      "description": "Access status for a single AI crawler from robots.txt.",
      "required": ["platform", "status"],
      "properties": {
        "platform": {
          "type": "string",
          "description": "AI platform name.",
          "examples": ["ChatGPT", "Claude", "Perplexity", "Gemini", "Bing Copilot"]
        },
        "userAgent": {
          "type": "string",
          "description": "Crawler user-agent string.",
          "examples": ["GPTBot", "ClaudeBot", "PerplexityBot", "Google-Extended", "Amazonbot"]
        },
        "status": {
          "type": "string",
          "enum": ["allowed", "blocked", "partially-blocked", "not-mentioned", "no-robots-txt"],
          "description": "Access determination from robots.txt."
        },
        "directives": {
          "type": "array",
          "description": "Raw robots.txt directives for this crawler.",
          "items": {
            "type": "object",
            "properties": {
              "directive": { "type": "string", "enum": ["allow", "disallow"] },
              "path": { "type": "string" }
            }
          }
        },
        "recommendation": { "type": "string" }
      }
    },

    "Action": {
      "type": "object",
      "description": "A prioritized remediation action.",
      "required": ["title"],
      "properties": {
        "title": {
          "type": "string",
          "description": "Concise action description."
        },
        "description": {
          "type": "string",
          "description": "Detailed implementation guidance."
        },
        "category": {
          "type": "string",
          "description": "Related scoring category id."
        },
        "pillar": {
          "type": "string",
          "description": "Scoring pillar this action affects."
        },
        "relatedFindings": {
          "type": "array",
          "items": { "type": "string" },
          "description": "ruleIds of findings this action addresses."
        },
        "effort": {
          "type": "string",
          "enum": ["trivial", "low", "medium", "high"]
        },
        "impact": {
          "type": "string",
          "enum": ["critical", "high", "medium", "low"]
        }
      }
    },

    "Rule": {
      "type": "object",
      "description": "Definition of an issue type the tool can report (SARIF: reportingDescriptor).",
      "required": ["id", "name", "shortDescription"],
      "properties": {
        "id": {
          "type": "string",
          "description": "Stable rule identifier (kebab-case).",
          "examples": ["missing-json-ld", "ai-crawler-blocked", "low-discovery-citation-rate"]
        },
        "name": {
          "type": "string",
          "description": "Human-readable rule name."
        },
        "shortDescription": { "type": "string" },
        "fullDescription": { "type": "string" },
        "helpUri": {
          "type": "string",
          "format": "uri",
          "description": "Link to detailed documentation."
        },
        "defaultSeverity": {
          "type": "string",
          "enum": ["critical", "high", "medium", "low", "info"]
        },
        "pillar": {
          "type": "string",
          "description": "Pillar affected by findings for this rule."
        }
      }
    }
  }
}