{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://github.com/DY-2026/GameDesignOS/game-experience-analyzer/templates/structured-output.schema.json",
  "title": "Game Experience Analyzer Structured Output",
  "description": "Strict core schema for evidence-linked game diagnosis outputs. For a filled example contract, see structured-output.example.json.",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "template_id",
    "analysis_mode",
    "video_meta",
    "tool_readiness",
    "sample_scope_gate",
    "diagnosis_route",
    "evidence_index",
    "analysis_route",
    "summary"
  ],
  "properties": {
    "template_id": {
      "type": "string",
      "minLength": 1
    },
    "analysis_mode": {
      "$ref": "#/$defs/analysis_mode"
    },
    "video_meta": {
      "$ref": "#/$defs/video_meta"
    },
    "tool_readiness": {
      "$ref": "#/$defs/tool_readiness"
    },
    "sample_scope_gate": {
      "$ref": "#/$defs/sample_scope_gate"
    },
    "diagnosis_route": {
      "$ref": "#/$defs/diagnosis_route"
    },
    "evidence_index": {
      "type": "array",
      "minItems": 1,
      "items": {
        "$ref": "#/$defs/evidence_item"
      }
    },
    "genre_route": {
      "type": "object"
    },
    "analysis_route": {
      "$ref": "#/$defs/analysis_route"
    },
    "visual_evidence": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/visual_evidence_item"
      }
    },
    "event_stream": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/event_stream_item"
      }
    },
    "stages": {
      "type": "array",
      "items": {
        "type": "object"
      }
    },
    "four_step_scores": {
      "type": "object"
    },
    "feature_ledger": {
      "type": "array",
      "items": {
        "type": "object"
      }
    },
    "system_design_review": {
      "type": "object"
    },
    "mda_analysis": {
      "type": "object"
    },
    "holistic_game_analysis": {
      "type": "object"
    },
    "gameplay_mechanics": {
      "type": "object"
    },
    "game_dissection_diagnosis": {
      "type": "object"
    },
    "single_player_design": {
      "type": "object"
    },
    "trailer_heat_prediction": {
      "$ref": "#/$defs/trailer_heat_prediction"
    },
    "foresight_opportunity": {
      "type": "object"
    },
    "commercialization": {
      "type": "object"
    },
    "ux_ui": {
      "type": "object"
    },
    "genre_benchmark": {
      "type": "object"
    },
    "problem_diagnosis": {
      "type": "object"
    },
    "liveops_longevity": {
      "type": "object"
    },
    "metrics": {
      "type": "object"
    },
    "summary": {
      "$ref": "#/$defs/summary"
    }
  },
  "$defs": {
    "analysis_mode": {
      "type": "string",
      "enum": [
        "early_experience",
        "gameplay_mechanics",
        "holistic_game_analysis",
        "whole_game_mda",
        "single_player_design",
        "trailer_heat_prediction",
        "foresight_opportunity",
        "commercialization",
        "ux_ui",
        "genre_benchmark",
        "problem_diagnosis",
        "liveops_longevity"
      ]
    },
    "diagnosis_pack": {
      "type": "string",
      "enum": [
        "pv_heat_diagnosis",
        "first_hour_retention_diagnosis",
        "core_loop_diagnosis",
        "game_dissection_diagnosis",
        "steam_page_conversion_diagnosis",
        "project_greenlight_risk_diagnosis",
        "monetization_interruption_diagnosis",
        "single_player_pacing_diagnosis",
        "none"
      ]
    },
    "confidence_label": {
      "type": "string",
      "enum": [
        "high",
        "medium",
        "low",
        "unsupported"
      ]
    },
    "readiness_status": {
      "type": "string",
      "enum": [
        "available",
        "missing",
        "blocked",
        "unknown",
        "not_checked",
        "not_applicable"
      ]
    },
    "string_or_null": {
      "type": [
        "string",
        "null"
      ]
    },
    "string_array": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "source_type": {
      "type": "string",
      "enum": [
        "screenshot",
        "video_file",
        "video_url",
        "trailer_pv",
        "paid_creative",
        "store_page",
        "local_recording",
        "first_hour_recording",
        "full_run_review",
        "user_context"
      ]
    },
    "event_type": {
      "type": "string",
      "enum": [
        "hook_peak",
        "feature_exposure",
        "feature_unlock",
        "first_use",
        "reward_claim",
        "failure_signal",
        "confusion_signal",
        "monetization_prompt",
        "decision_point",
        "shareable_moment",
        "control_release",
        "loop_closure",
        "access_blocked"
      ]
    },
    "video_meta": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "source_items"
      ],
      "properties": {
        "game_name": {
          "$ref": "#/$defs/string_or_null"
        },
        "platform": {
          "type": "string"
        },
        "version": {
          "$ref": "#/$defs/string_or_null"
        },
        "session_scope": {
          "type": "string"
        },
        "expected_genre": {
          "type": "string"
        },
        "source_items": {
          "type": "array",
          "minItems": 1,
          "items": {
            "$ref": "#/$defs/source_item"
          }
        },
        "has_voice": {
          "type": "string",
          "enum": [
            "yes",
            "no",
            "unknown"
          ]
        },
        "has_subtitle": {
          "type": "string",
          "enum": [
            "yes",
            "no",
            "unknown"
          ]
        }
      }
    },
    "source_item": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "type",
        "label"
      ],
      "properties": {
        "type": {
          "$ref": "#/$defs/source_type"
        },
        "path": {
          "$ref": "#/$defs/string_or_null"
        },
        "url": {
          "$ref": "#/$defs/string_or_null"
        },
        "label": {
          "$ref": "#/$defs/string_or_null"
        },
        "time_range": {
          "$ref": "#/$defs/string_or_null"
        },
        "accessed_at": {
          "$ref": "#/$defs/string_or_null"
        },
        "access_notes": {
          "$ref": "#/$defs/string_or_null"
        }
      }
    },
    "tool_readiness": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "access_notes",
        "degradation"
      ],
      "properties": {
        "browser_access": {
          "$ref": "#/$defs/readiness_status"
        },
        "ffmpeg": {
          "$ref": "#/$defs/readiness_status"
        },
        "yt_dlp": {
          "$ref": "#/$defs/readiness_status"
        },
        "ocr": {
          "$ref": "#/$defs/readiness_status"
        },
        "asr": {
          "$ref": "#/$defs/readiness_status"
        },
        "access_notes": {
          "type": "string"
        },
        "degradation": {
          "type": "string"
        }
      }
    },
    "sample_scope_gate": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "sample_boundary",
        "supported_judgment_scope",
        "unsupported_judgment_scope",
        "key_unknowns",
        "confidence_ceiling"
      ],
      "properties": {
        "sample_boundary": {
          "type": "string",
          "minLength": 1
        },
        "supported_judgment_scope": {
          "$ref": "#/$defs/string_array"
        },
        "unsupported_judgment_scope": {
          "$ref": "#/$defs/string_array"
        },
        "key_unknowns": {
          "$ref": "#/$defs/string_array"
        },
        "confidence_ceiling": {
          "$ref": "#/$defs/confidence_label"
        }
      }
    },
    "diagnosis_route": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "diagnosis_pack",
        "primary_modes",
        "supporting_modes",
        "required_sections",
        "not_enabled"
      ],
      "properties": {
        "diagnosis_pack": {
          "$ref": "#/$defs/diagnosis_pack"
        },
        "primary_modes": {
          "type": "array",
          "minItems": 1,
          "items": {
            "$ref": "#/$defs/analysis_mode"
          }
        },
        "supporting_modes": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/analysis_mode"
          }
        },
        "required_sections": {
          "$ref": "#/$defs/string_array"
        },
        "not_enabled": {
          "$ref": "#/$defs/string_array"
        }
      }
    },
    "evidence_item": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "evidence_id",
        "source_type",
        "observed_fact",
        "event_type",
        "supports_judgment",
        "confidence",
        "extraction_method"
      ],
      "properties": {
        "evidence_id": {
          "type": "string",
          "pattern": "^E[0-9]{3,}$"
        },
        "source_id": {
          "$ref": "#/$defs/string_or_null"
        },
        "source_type": {
          "$ref": "#/$defs/source_type"
        },
        "timestamp": {
          "$ref": "#/$defs/string_or_null"
        },
        "time_range": {
          "$ref": "#/$defs/string_or_null"
        },
        "frame_id": {
          "$ref": "#/$defs/string_or_null"
        },
        "image_id": {
          "$ref": "#/$defs/string_or_null"
        },
        "region": {
          "type": "string"
        },
        "visible_text": {
          "type": "string"
        },
        "observed_fact": {
          "type": "string",
          "minLength": 1
        },
        "event_type": {
          "$ref": "#/$defs/event_type"
        },
        "supports_judgment": {
          "type": "string"
        },
        "confidence": {
          "type": "number",
          "minimum": 0,
          "maximum": 1
        },
        "uncertainty_note": {
          "type": "string"
        },
        "extraction_method": {
          "type": "string",
          "enum": [
            "direct_observation",
            "frame_sample",
            "ocr",
            "page_metadata",
            "user_provided",
            "synthetic_example"
          ]
        }
      }
    },
    "analysis_route": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "mode",
        "reason",
        "selected_lenses",
        "core_questions",
        "required_sections",
        "not_answered"
      ],
      "properties": {
        "mode": {
          "anyOf": [
            {
              "$ref": "#/$defs/analysis_mode"
            },
            {
              "type": "null"
            }
          ]
        },
        "reason": {
          "type": "string"
        },
        "selected_lenses": {
          "$ref": "#/$defs/string_array"
        },
        "core_questions": {
          "$ref": "#/$defs/string_array"
        },
        "required_sections": {
          "$ref": "#/$defs/string_array"
        },
        "not_answered": {
          "$ref": "#/$defs/string_array"
        }
      }
    },
    "visual_evidence_item": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "evidence_id",
        "evidence",
        "confidence"
      ],
      "properties": {
        "evidence_id": {
          "type": "string"
        },
        "image_id": {
          "$ref": "#/$defs/string_or_null"
        },
        "timestamp": {
          "$ref": "#/$defs/string_or_null"
        },
        "source_label": {
          "$ref": "#/$defs/string_or_null"
        },
        "region": {
          "type": "string"
        },
        "visible_text": {
          "type": "string"
        },
        "evidence": {
          "type": "string"
        },
        "confidence": {
          "type": "number",
          "minimum": 0,
          "maximum": 1
        }
      }
    },
    "event_stream_item": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "evidence_id",
        "evidence_locator",
        "event_type",
        "evidence",
        "confidence"
      ],
      "properties": {
        "evidence_id": {
          "type": "string"
        },
        "timestamp": {
          "$ref": "#/$defs/string_or_null"
        },
        "image_id": {
          "$ref": "#/$defs/string_or_null"
        },
        "evidence_locator": {
          "type": "string"
        },
        "type": {
          "type": "string"
        },
        "event_type": {
          "$ref": "#/$defs/event_type"
        },
        "system_tag": {
          "$ref": "#/$defs/string_or_null"
        },
        "feature_tag": {
          "$ref": "#/$defs/string_or_null"
        },
        "evidence": {
          "type": "string"
        },
        "confidence": {
          "type": "number",
          "minimum": 0,
          "maximum": 1
        },
        "state": {
          "type": "string"
        }
      }
    },
    "trailer_heat_prediction": {
      "type": "object",
      "additionalProperties": true,
      "properties": {
        "trailer_type": {
          "type": "string"
        },
        "first_3_6_seconds_hook": {
          "type": "array"
        },
        "one_sentence_pitch": {
          "type": "string"
        },
        "proof_of_play": {
          "type": "array"
        },
        "heat_potential_tier": {
          "type": "string",
          "enum": [
            "blockbuster_candidate",
            "strong_niche_hit",
            "needs_validation",
            "high_risk",
            "insufficient_evidence"
          ]
        },
        "confidence": {
          "$ref": "#/$defs/confidence_label"
        },
        "key_uncertainties": {
          "$ref": "#/$defs/string_array"
        },
        "validation_plan": {
          "type": "array"
        }
      }
    },
    "summary": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "one_line",
        "issues",
        "recommendations"
      ],
      "properties": {
        "one_line": {
          "type": "string"
        },
        "issues": {
          "type": "array",
          "items": {
            "type": "object"
          }
        },
        "recommendations": {
          "type": "array",
          "items": {
            "type": "object"
          }
        }
      }
    }
  }
}