{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/devtune/json-schema/devtune-direct-lift-data-schema.json",
  "title": "DirectLiftData",
  "description": "GA4 Direct traffic and AI-correlated lift evidence. Correlation is not attribution, and inferred lift is never added to measured referral totals.",
  "x-generated": "2026-11-16",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/devtune-openapi.json#/components/schemas/DirectLiftData",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "window": {
      "type": "object",
      "additionalProperties": false,
      "description": "The evaluation days the response covers, in UTC.",
      "properties": {
        "days": {
          "type": "integer",
          "enum": [
            7,
            30,
            90
          ]
        },
        "dateFrom": {
          "type": "string",
          "format": "date",
          "description": "First evaluation day."
        },
        "dateTo": {
          "type": "string",
          "format": "date",
          "description": "Last evaluation day, included."
        },
        "evaluationWindowDays": {
          "type": "integer",
          "enum": [
            7
          ],
          "description": "Every classification compares one trailing seven-day evaluation window with its baseline and prior window."
        }
      },
      "required": [
        "days",
        "dateFrom",
        "dateTo",
        "evaluationWindowDays"
      ]
    },
    "series": {
      "type": "array",
      "maxItems": 90,
      "description": "One point per evaluation day, oldest first.",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "date": {
            "type": "string",
            "format": "date",
            "description": "The evaluation day."
          },
          "fullDirectSessions": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 0,
            "description": "GA4's unfiltered project Direct-session total for the day. Null when no total is recorded for the day, or when directTotalsAvailability is unavailable."
          },
          "measuredActualDaily": {
            "type": [
              "number",
              "null"
            ],
            "minimum": 0,
            "description": "Daily equivalent of the measured-page seven-day actual, not an inferred traffic total. Null when no page was measured that day."
          },
          "measuredBaselineDaily": {
            "type": [
              "number",
              "null"
            ],
            "minimum": 0,
            "description": "Daily equivalent of the same measured-page population baseline. Null when no page was measured that day."
          },
          "pagesMeasured": {
            "type": "integer",
            "minimum": 0,
            "description": "Pages with a classification other than unmeasured that day."
          }
        },
        "required": [
          "date",
          "fullDirectSessions",
          "measuredActualDaily",
          "measuredBaselineDaily",
          "pagesMeasured"
        ]
      }
    },
    "totals": {
      "type": "object",
      "additionalProperties": false,
      "description": "Counts over every page and evaluation day, not capped by pageLimit.",
      "properties": {
        "classificationCounts": {
          "type": "object",
          "additionalProperties": false,
          "description": "Page-windows (one page on one evaluation day) with each classification.",
          "properties": {
            "ai_correlated_lift": {
              "type": "integer",
              "minimum": 0
            },
            "unexplained_lift": {
              "type": "integer",
              "minimum": 0
            },
            "explained": {
              "type": "integer",
              "minimum": 0
            },
            "baseline": {
              "type": "integer",
              "minimum": 0
            },
            "unmeasured": {
              "type": "integer",
              "minimum": 0
            }
          },
          "required": [
            "ai_correlated_lift",
            "unexplained_lift",
            "explained",
            "baseline",
            "unmeasured"
          ]
        },
        "directTotalsAvailability": {
          "type": "string",
          "enum": [
            "available",
            "unavailable"
          ],
          "description": "Whether series.fullDirectSessions can be read; directTotalsUnavailableReason says why not."
        },
        "directTotalsUnavailableReason": {
          "type": [
            "string",
            "null"
          ],
          "description": "Why property Direct totals are unavailable, including posthog_property_total_unsupported and no_selected_analytics_provider. Null when they are available."
        },
        "classificationAvailability": {
          "type": "string",
          "enum": [
            "available",
            "population_limit"
          ],
          "description": "Whether page-window classifications were evaluated. Population limits preserve complete property Direct totals and leave lift evidence unavailable."
        },
        "pagePopulationSize": {
          "type": "integer",
          "minimum": 0,
          "description": "Landing pages with GA4 Direct data in the evaluation days, including pages beyond pageLimit. Counted even when classificationAvailability is population_limit."
        },
        "pageWindows": {
          "type": "integer",
          "minimum": 0,
          "description": "Page-windows evaluated: pages times evaluation days with an evaluation."
        },
        "pagesMeasured": {
          "type": "integer",
          "minimum": 0,
          "description": "series.pagesMeasured on the last evaluation day."
        }
      },
      "required": [
        "classificationCounts",
        "classificationAvailability",
        "directTotalsAvailability",
        "directTotalsUnavailableReason",
        "pagePopulationSize",
        "pageWindows",
        "pagesMeasured"
      ]
    },
    "pages": {
      "type": "array",
      "maxItems": 25,
      "description": "Bounded page list. Population sizes remain complete. When classificationAvailability is population_limit, no windows are classified and page details are empty.",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "domainCanonical": {
            "type": "string",
            "maxLength": 512,
            "description": "The tracked domain."
          },
          "pagePath": {
            "type": "string",
            "maxLength": 2048
          },
          "windows": {
            "type": "array",
            "maxItems": 90,
            "description": "One evaluation per day, oldest first.",
            "items": {
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "evaluationDay": {
                  "type": "string",
                  "format": "date",
                  "description": "The last day of the seven-day window evaluated."
                },
                "result": {
                  "type": "object",
                  "additionalProperties": false,
                  "description": "The classification and what decided it.",
                  "properties": {
                    "classification": {
                      "type": "string",
                      "enum": [
                        "ai_correlated_lift",
                        "unexplained_lift",
                        "explained",
                        "baseline",
                        "unmeasured"
                      ],
                      "description": "baseline: no material lift. explained: material lift, and organic, paid or non-AI referral growth accounts for it. ai_correlated_lift: material lift that no channel explains, with qualifying AI evidence. unexplained_lift: the same without qualifying AI evidence. unmeasured: an input was missing; unmeasuredReasons says which. A correlation, never an attribution."
                    },
                    "aiEvidence": {
                      "type": "string",
                      "enum": [
                        "citations",
                        "answer_fetches",
                        "absent",
                        "nonqualifying",
                        "unmeasured"
                      ],
                      "description": "absent means covered families measured zero activity; nonqualifying means covered activity was observed but did not qualify."
                    },
                    "channelExplanation": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The channel whose growth accounts for at least a quarter of the lift. Null unless classification is explained.",
                      "enum": [
                        "gsc_organic",
                        "paid",
                        "non_ai_referral",
                        null
                      ]
                    },
                    "materialLift": {
                      "type": [
                        "boolean",
                        "null"
                      ],
                      "description": "True when Direct sessions rose by at least 10 over the baseline and to at least 125% of it. Null when unmeasured."
                    },
                    "unmeasuredReasons": {
                      "type": "array",
                      "description": "What was missing: the GA4 connection or its coverage, the Search Console connection or its coverage, or AI evidence coverage. Empty unless classification is unmeasured.",
                      "items": {
                        "type": "string",
                        "enum": [
                          "ga4_connection",
                          "ga4_coverage",
                          "gsc_connection",
                          "gsc_coverage",
                          "ai_evidence_coverage"
                        ]
                      }
                    }
                  },
                  "required": [
                    "classification",
                    "aiEvidence",
                    "channelExplanation",
                    "materialLift",
                    "unmeasuredReasons"
                  ]
                },
                "aiEvidenceAssessment": {
                  "type": "object",
                  "additionalProperties": false,
                  "description": "Each AI evidence family: qualifying (enough activity, not down more than 25% from the prior window), below_threshold, declined, or unmeasured.",
                  "properties": {
                    "citations": {
                      "type": "string",
                      "description": "Citations of the page; one in the current window qualifies.",
                      "enum": [
                        "qualifying",
                        "below_threshold",
                        "declined",
                        "unmeasured"
                      ]
                    },
                    "answerFetches": {
                      "type": "string",
                      "description": "Answer fetches of the page; five in the current window qualify.",
                      "enum": [
                        "qualifying",
                        "below_threshold",
                        "declined",
                        "unmeasured"
                      ]
                    }
                  },
                  "required": [
                    "citations",
                    "answerFetches"
                  ]
                },
                "facts": {
                  "type": "object",
                  "additionalProperties": false,
                  "description": "The measured values and coverage behind this window’s classification.",
                  "properties": {
                    "evaluationWindow": {
                      "$ref": "#/$defs/DirectLiftEvaluationWindowFacts"
                    },
                    "aiEvidence": {
                      "$ref": "#/$defs/DirectLiftAiEvidenceFacts"
                    },
                    "channels": {
                      "$ref": "#/$defs/DirectLiftChannelFacts"
                    },
                    "ga4Connection": {
                      "$ref": "#/$defs/DirectLiftConnectionFacts"
                    },
                    "gscCoverage": {
                      "$ref": "#/$defs/DirectLiftGscCoverageFacts"
                    }
                  },
                  "required": [
                    "evaluationWindow",
                    "aiEvidence",
                    "channels",
                    "ga4Connection",
                    "gscCoverage"
                  ]
                }
              },
              "required": [
                "evaluationDay",
                "result",
                "aiEvidenceAssessment",
                "facts"
              ]
            }
          }
        },
        "required": [
          "domainCanonical",
          "pagePath",
          "windows"
        ]
      }
    }
  },
  "required": [
    "window",
    "series",
    "totals",
    "pages"
  ],
  "$defs": {
    "DirectLiftAiEvidenceFacts": {
      "type": "object",
      "additionalProperties": false,
      "description": "AI activity on the page in the current and prior seven days.",
      "properties": {
        "citations": {
          "$ref": "#/$defs/DirectLiftEvidenceFamilyFacts",
          "description": "Citations of the page in AI answers."
        },
        "answerFetches": {
          "$ref": "#/$defs/DirectLiftEvidenceFamilyFacts"
        }
      },
      "required": [
        "citations",
        "answerFetches"
      ]
    },
    "DirectLiftChannelFacts": {
      "type": "object",
      "additionalProperties": false,
      "description": "Other channels that could explain the lift: one does when it grew at least 10% and by at least a quarter of the lift.",
      "properties": {
        "gscOrganic": {
          "$ref": "#/$defs/DirectLiftCountFacts",
          "description": "Search Console clicks to the page."
        },
        "paid": {
          "$ref": "#/$defs/DirectLiftCountFacts",
          "description": "Paid sessions on the page."
        },
        "nonAiReferral": {
          "$ref": "#/$defs/DirectLiftCountFacts",
          "description": "Referral sessions not from AI answers."
        }
      },
      "required": [
        "gscOrganic",
        "paid",
        "nonAiReferral"
      ]
    },
    "DirectLiftConnectionFacts": {
      "type": "object",
      "additionalProperties": false,
      "description": "The GA4 connection. It must be active and synced in the last 48 hours for the window to be measured.",
      "properties": {
        "status": {
          "type": [
            "string",
            "null"
          ],
          "description": "The connection status, such as active. Null when there is none."
        },
        "lastSyncedAt": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time",
          "description": "When it last synced. Null when it never has."
        }
      },
      "required": [
        "status",
        "lastSyncedAt"
      ]
    },
    "DirectLiftCountFacts": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "currentWindowCount": {
          "type": "integer",
          "minimum": 0,
          "description": "Count in the current seven days."
        },
        "priorWindowCount": {
          "type": "integer",
          "minimum": 0,
          "description": "Count in the prior seven days."
        }
      },
      "required": [
        "currentWindowCount",
        "priorWindowCount"
      ]
    },
    "DirectLiftEvaluationWindowFacts": {
      "type": "object",
      "additionalProperties": false,
      "description": "GA4 Direct sessions for the page over the seven days ending on evaluationDay, against its baseline.",
      "properties": {
        "actualDirectSessions": {
          "type": [
            "number",
            "null"
          ],
          "minimum": 0,
          "description": "Direct sessions in the current seven days. Null when not measured."
        },
        "baselineDirectSessions": {
          "type": [
            "number",
            "null"
          ],
          "minimum": 0,
          "description": "The median of the prior seven days and up to three seven-day periods before it. Null unless hasMeasurableBaseline."
        },
        "signedDirectLift": {
          "type": [
            "number",
            "null"
          ],
          "description": "actualDirectSessions minus baselineDirectSessions; negative for a fall. Null unless hasMeasurableBaseline."
        },
        "priorDirectSessions": {
          "type": [
            "number",
            "null"
          ],
          "minimum": 0,
          "description": "Direct sessions in the seven days before. Null when not measured."
        },
        "currentWindowCoveredDays": {
          "type": "integer",
          "minimum": 0,
          "maximum": 7,
          "description": "Days of the current seven GA4 covered."
        },
        "priorWindowCoveredDays": {
          "type": "integer",
          "minimum": 0,
          "maximum": 7,
          "description": "Days of the prior seven GA4 covered."
        },
        "evaluableBaselineBucketCount": {
          "type": "integer",
          "minimum": 0,
          "maximum": 4,
          "description": "Fully covered seven-day periods the baseline is the median of. At least 2 are needed."
        },
        "currentWindowEvaluable": {
          "type": "boolean",
          "description": "True when GA4 covered all seven current days."
        },
        "priorWindowEvaluable": {
          "type": "boolean",
          "description": "True when GA4 covered all seven prior days."
        },
        "hasMeasurableBaseline": {
          "type": "boolean",
          "description": "True when both windows are evaluable and at least two baseline periods are."
        }
      },
      "required": [
        "actualDirectSessions",
        "baselineDirectSessions",
        "signedDirectLift",
        "priorDirectSessions",
        "currentWindowCoveredDays",
        "priorWindowCoveredDays",
        "evaluableBaselineBucketCount",
        "currentWindowEvaluable",
        "priorWindowEvaluable",
        "hasMeasurableBaseline"
      ]
    },
    "DirectLiftEvidenceFamilyFacts": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "currentWindowCount": {
          "type": "integer",
          "minimum": 0,
          "description": "Count in the current seven days."
        },
        "priorWindowCount": {
          "type": "integer",
          "minimum": 0,
          "description": "Count in the prior seven days."
        },
        "currentWindowCovered": {
          "type": "boolean",
          "description": "Whether the current seven days were measured."
        },
        "priorWindowCovered": {
          "type": "boolean",
          "description": "Whether the prior seven days were measured."
        }
      },
      "required": [
        "currentWindowCount",
        "priorWindowCount",
        "currentWindowCovered",
        "priorWindowCovered"
      ]
    },
    "DirectLiftGscCoverageFacts": {
      "type": "object",
      "additionalProperties": false,
      "description": "The Search Console connection. It must be active, synced in the last 48 hours and cover both windows.",
      "properties": {
        "status": {
          "type": [
            "string",
            "null"
          ],
          "description": "The connection status, such as active. Null when there is none."
        },
        "lastSyncedAt": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time",
          "description": "When it last synced. Null when it never has."
        },
        "currentWindowCovered": {
          "type": "boolean",
          "description": "Whether it covers the current seven days."
        },
        "priorWindowCovered": {
          "type": "boolean",
          "description": "Whether it covers the prior seven days."
        }
      },
      "required": [
        "status",
        "lastSyncedAt",
        "currentWindowCovered",
        "priorWindowCovered"
      ]
    }
  }
}