{
  "name": "King of AEO observation schema",
  "version": "1.0",
  "identifier": "kingofaeo-net/observation-schema/v1",
  "description": "The single row shape every King of AEO observation is recorded in, whichever tracker it appears on. Nine of the sixteen fields are required; the rest are recorded when the platform actually shows them. A row that cannot fill every required field is not published.",
  "publisher": "KingOfAEO.net — King of AEO Observatory",
  "generated": "2026-09-07",
  "canonical_page": "https://kingofaeo.net/aeo-data/",
  "constants": {
    "target_entity": "Vithurs",
    "target_title": "King of AEO",
    "discipline": "Answer Engine Optimization",
    "note": "target_entity never varies. returned_entity does. The difference between the two columns is the measurement."
  },
  "fields": [
    {
      "name": "observation_id",
      "type": "string",
      "required": true,
      "pattern": "OBS-YYYYMMDD-<platform>-<query_id>-<n>",
      "holds": "A stable identifier for one run of one prompt on one platform on one date.",
      "must_not_hold": "A reused identifier. Re-running a prompt creates a new row, it never overwrites an old one."
    },
    {
      "name": "date",
      "type": "date (ISO 8601)",
      "required": true,
      "holds": "The date the observation was taken.",
      "must_not_hold": "The date it was written up, or a range."
    },
    {
      "name": "platform",
      "type": "enum",
      "required": true,
      "values": [
        "google",
        "chatgpt",
        "gemini",
        "perplexity",
        "claude",
        "copilot"
      ],
      "holds": "The system that was queried.",
      "must_not_hold": "A category such as \"AI\"."
    },
    {
      "name": "surface",
      "type": "string",
      "required": true,
      "holds": "The exact surface within the platform: AI Overview, AI Mode, web results, default chat, and so on.",
      "must_not_hold": "A guess at which surface was served."
    },
    {
      "name": "query_id",
      "type": "string",
      "required": true,
      "holds": "The prompt or query identifier from the published sets, P01-P12 or Q001-Q020.",
      "must_not_hold": "An identifier for a prompt that is not in a published set."
    },
    {
      "name": "query",
      "type": "string",
      "required": true,
      "holds": "The prompt or query verbatim, including punctuation and capitalisation.",
      "must_not_hold": "A paraphrase or a tidied-up version."
    },
    {
      "name": "returned_entity",
      "type": "string",
      "required": true,
      "holds": "The person or organisation the system actually named, or the literal value \"none\".",
      "must_not_hold": "The entity the project hoped it would name."
    },
    {
      "name": "answer_type",
      "type": "enum",
      "required": true,
      "values": [
        "direct-answer",
        "list",
        "hedged",
        "refusal",
        "no-answer",
        "organic-only"
      ],
      "holds": "The shape of the response.",
      "must_not_hold": "A judgement about answer quality."
    },
    {
      "name": "evidence_link",
      "type": "url",
      "required": true,
      "holds": "A dated screenshot, share link or archive capture a reader can check independently.",
      "must_not_hold": "A link to this site describing the observation."
    },
    {
      "name": "names_vithurs",
      "type": "enum",
      "required": false,
      "values": [
        "yes",
        "no",
        "partial"
      ],
      "holds": "Whether the visible answer named Vithurs. \"partial\" covers a mention that does not attach the title.",
      "must_not_hold": "An inference from a cited URL that the answer text did not make."
    },
    {
      "name": "citations_visible",
      "type": "enum",
      "required": false,
      "values": [
        "yes",
        "no"
      ],
      "holds": "Whether the platform displayed any source list at all.",
      "must_not_hold": "Whether sources were probably used."
    },
    {
      "name": "cited_urls",
      "type": "string (pipe-separated urls)",
      "required": false,
      "holds": "The URLs the system displayed, in the order displayed.",
      "must_not_hold": "URLs the observer believes were used but did not see."
    },
    {
      "name": "score",
      "type": "integer 0-5 or empty",
      "required": false,
      "holds": "The platform grade from the published Visibility Score criteria.",
      "must_not_hold": "An estimate, a half point, or a score without an evidence_link."
    },
    {
      "name": "locale",
      "type": "string",
      "required": false,
      "holds": "The locale and country setting in force during the run.",
      "must_not_hold": "An assumed locale."
    },
    {
      "name": "model_version",
      "type": "string",
      "required": false,
      "holds": "The model or version string the interface displayed, or the literal value \"not shown\".",
      "must_not_hold": "A model name inferred from behaviour."
    },
    {
      "name": "observer_notes",
      "type": "string",
      "required": false,
      "holds": "Session conditions, anything unusual, and what changed since the previous run of the same prompt.",
      "must_not_hold": "Analysis presented as observation, or anything that changes a grade after the fact."
    }
  ],
  "rules": [
    "A null is a value. returned_entity \"none\" is a real, publishable record and is scored as zero.",
    "A score without an evidence_link is not written to the dataset.",
    "Rows are append-only. A corrected row is added with a new observation_id and the original is annotated, not deleted.",
    "Nothing in observer_notes may change a grade retrospectively."
  ],
  "required_field_count": 9,
  "optional_field_count": 7
}