{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://www.hussh.si/analytics-schema.json",
  "title": "hussh first-party product event envelope",
  "description": "Descriptive schema for POST /api/analytics/event. Not an independent audit or a guarantee that Google collects only these fields. Metadata is extensible, not a strict allowlist. Identity can be attached by the server outside this envelope.",
  "type": "object",
  "required": ["event_name"],
  "properties": {
    "event_name": { "type": "string", "minLength": 1, "maxLength": 80 },
    "page_path": { "type": ["string", "null"], "maxLength": 500, "description": "Browser helper removes query strings; search q values are replaced with <redacted>." },
    "metadata": {
      "type": "object",
      "description": "Representative fields, not an exhaustive event catalog. Browser helper filters keys containing answer, conversation, prompt, query, raw or transcript, except approved length/count keys.",
      "properties": {
        "session_id": { "type": "string", "description": "App session identifier; not an aggregate count." },
        "query_length": { "type": "number" },
        "answer_length": { "type": "number" },
        "source_count": { "type": "number" },
        "follow_up_count": { "type": "number" },
        "signed_in": { "type": "boolean" },
        "request_type": { "type": "string" },
        "cta_label": { "type": "string" },
        "cta_destination": { "type": "string" },
        "model_key": { "type": "string" },
        "device_class": { "type": "string" },
        "browser_family": { "type": "string" },
        "progress_bucket": { "type": "number" },
        "metric_name": { "type": "string" },
        "metric_value": { "type": "number", "description": "Rounded measurement, not a bucketed count." },
        "metric_rating": { "type": "string" },
        "metric_id": { "type": "string" }
      },
      "additionalProperties": true
    }
  },
  "additionalProperties": false,
  "x-server-identity": ["authenticated user ID when signed in", "anonymous identifier", "session ID when supplied"],
  "x-google-collection": "GA4 and optional GTM run separately. Google may collect browser, device and network information. Analytics storage defaults to denied and follows the PCHP grant.",
  "x-sources": [
    "https://github.com/hushh-labs/hushh-search-console/blob/main/src/lib/analytics/client.ts",
    "https://github.com/hushh-labs/hushh-search-console/blob/main/src/components/analytics/AnalyticsScripts.tsx",
    "https://github.com/hushh-labs/hushh-search-console/blob/main/backend/app/api/analytics.py",
    "https://github.com/hushh-labs/hushh-search-console/blob/main/backend/app/models/schemas.py"
  ]
}