{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Arrow GEO observation: one attempt per JSONL line",
  "description": "Primary Arrow GEO v2 observation. Optional ranking and factChecks remain null/unmeasured until reviewed. Use the CLI for panel, context, evidence and lifecycle consistency. Use the archived v1 schema for legacy downstream-panel records.",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "id",
    "sampleId",
    "sessionId",
    "sessionContext",
    "panelVersion",
    "promptId",
    "promptText",
    "observedAt",
    "surface",
    "model",
    "collectionMethod",
    "language",
    "market",
    "observedCountry",
    "locationMethod",
    "subject",
    "status",
    "overviewPresent",
    "rawResponse",
    "evidenceRefs",
    "errorReason",
    "classification",
    "sourceUrls",
    "reviewedBy",
    "reviewedAt"
  ],
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1
    },
    "sampleId": {
      "type": "string",
      "minLength": 1
    },
    "sessionId": {
      "type": "string",
      "minLength": 1
    },
    "panelVersion": {
      "const": "arrow-geo-panel-2026-09-08.v2"
    },
    "promptId": {
      "type": "string"
    },
    "promptText": {
      "type": "string",
      "minLength": 1
    },
    "observedAt": {
      "type": "string",
      "format": "date-time"
    },
    "surface": {
      "type": "string",
      "pattern": "^(?:chatgpt_search|perplexity|google_ai_mode|google_ai_overviews|claude_search|gemini|copilot|api/[a-zA-Z0-9][a-zA-Z0-9_-]*/[a-zA-Z0-9][a-zA-Z0-9_-]*)$",
      "description": "Public: chatgpt_search, perplexity, google_ai_mode, google_ai_overviews, claude_search, gemini, copilot. APIs require all three components: api/<provider>/<configuration>."
    },
    "model": {
      "type": "string",
      "minLength": 1,
      "description": "Exact known model/version, or not_disclosed."
    },
    "collectionMethod": {
      "enum": [
        "public_interface",
        "api"
      ]
    },
    "language": {
      "enum": [
        "en",
        "fr"
      ]
    },
    "market": {
      "type": "string",
      "description": "Must match panel's intended market; does not assert geolocation."
    },
    "observedCountry": {
      "type": [
        "string",
        "null"
      ],
      "pattern": "^[A-Z]{2}$"
    },
    "locationMethod": {
      "enum": [
        "unavailable",
        "account_setting",
        "explicit_ui",
        "other_recorded"
      ]
    },
    "subject": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "id",
        "name",
        "kind",
        "domain"
      ],
      "properties": {
        "id": {
          "type": "string",
          "minLength": 1
        },
        "name": {
          "type": "string",
          "minLength": 1
        },
        "kind": {
          "enum": [
            "geo_platform",
            "yacht_brokerage",
            "dpe_provider"
          ]
        },
        "domain": {
          "type": "string",
          "description": "Hostname only; used to validate citations."
        }
      }
    },
    "status": {
      "enum": [
        "valid",
        "error",
        "unavailable"
      ]
    },
    "overviewPresent": {
      "type": [
        "boolean",
        "null"
      ],
      "description": "Required boolean only for a valid Google AI Overviews observation; otherwise null."
    },
    "rawResponse": {
      "type": [
        "string",
        "null"
      ],
      "description": "Actual full answer required for valid responses, except a recorded non-triggering AI Overview."
    },
    "evidenceRefs": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "string",
        "minLength": 1
      },
      "description": "Real capture/shared-result/local evidence references; never invented."
    },
    "errorReason": {
      "type": [
        "string",
        "null"
      ]
    },
    "classification": {
      "type": [
        "object",
        "null"
      ],
      "additionalProperties": false,
      "required": [
        "mentioned",
        "recommended",
        "citationUrls",
        "identityCorrect"
      ],
      "properties": {
        "mentioned": {
          "type": "boolean"
        },
        "recommended": {
          "type": "boolean"
        },
        "citationUrls": {
          "type": "array",
          "uniqueItems": true,
          "items": {
            "type": "string",
            "format": "uri"
          }
        },
        "identityCorrect": {
          "type": [
            "boolean",
            "null"
          ]
        }
      }
    },
    "sourceUrls": {
      "type": "array",
      "uniqueItems": true,
      "items": {
        "type": "string",
        "format": "uri"
      }
    },
    "reviewedBy": {
      "type": [
        "string",
        "null"
      ]
    },
    "reviewedAt": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "sessionContext": {
      "enum": [
        "fresh_logged_out",
        "fresh_logged_in",
        "existing_conversation",
        "api_stateless",
        "api_stateful",
        "unknown"
      ],
      "description": "Declared session conditions. Reports and paired comparisons separate these contexts."
    },
    "ranking": {
      "description": "Optional reviewed list classification. Null or absent means not measured. Only explicitly ordered lists can establish a position. Evidence must belong to the observed response.",
      "anyOf": [
        {
          "type": "null"
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "explicitlyOrdered",
            "subjectPosition",
            "listLength",
            "evidenceRefs"
          ],
          "properties": {
            "explicitlyOrdered": {
              "type": "boolean"
            },
            "subjectPosition": {
              "type": [
                "integer",
                "null"
              ],
              "minimum": 1
            },
            "listLength": {
              "type": [
                "integer",
                "null"
              ],
              "minimum": 1
            },
            "evidenceRefs": {
              "type": "array",
              "minItems": 1,
              "uniqueItems": true,
              "items": {
                "type": "string",
                "minLength": 1
              }
            }
          },
          "allOf": [
            {
              "if": {
                "properties": {
                  "explicitlyOrdered": {
                    "const": false
                  }
                }
              },
              "then": {
                "properties": {
                  "subjectPosition": {
                    "type": "null"
                  },
                  "listLength": {
                    "type": "null"
                  }
                }
              },
              "else": {
                "properties": {
                  "listLength": {
                    "type": "integer",
                    "minimum": 1
                  }
                }
              }
            }
          ]
        }
      ]
    },
    "factChecks": {
      "description": "Optional checks of claims about the evaluated subject. Null/absent means not reviewed; an empty array means reviewed with no eligible claims. Reference evidence and a version/date are required. Unverifiable verdicts are excluded from the accuracy denominator.",
      "anyOf": [
        {
          "type": "null"
        },
        {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "id",
              "claim",
              "category",
              "verdict",
              "referenceUrls",
              "referenceVersion",
              "checkedAt",
              "evidenceRefs"
            ],
            "properties": {
              "id": {
                "type": "string",
                "minLength": 1
              },
              "claim": {
                "type": "string",
                "minLength": 1,
                "description": "Exact extract from rawResponse, about the evaluated subject."
              },
              "category": {
                "enum": [
                  "price",
                  "feature",
                  "category",
                  "limit"
                ]
              },
              "verdict": {
                "enum": [
                  "correct",
                  "incorrect",
                  "unverifiable"
                ]
              },
              "referenceUrls": {
                "type": "array",
                "minItems": 1,
                "uniqueItems": true,
                "items": {
                  "type": "string",
                  "format": "uri"
                }
              },
              "referenceVersion": {
                "type": "string",
                "minLength": 1,
                "description": "Exact dated/versioned source used to check the claim."
              },
              "checkedAt": {
                "type": "string",
                "format": "date-time"
              },
              "evidenceRefs": {
                "type": "array",
                "minItems": 1,
                "uniqueItems": true,
                "items": {
                  "type": "string",
                  "minLength": 1
                }
              }
            }
          }
        }
      ]
    }
  }
}