{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/machina-gg/json-schema/machina-gg-spotlight-response-schema.json",
  "title": "SpotlightResponse",
  "x-generated": "2026-11-17",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/machina-gg-openapi.json#/components/schemas/SpotlightResponse",
  "allOf": [
    {
      "$ref": "#/$defs/ResponseBase"
    },
    {
      "type": "object",
      "required": [
        "skill_card",
        "structured_retrospective",
        "content_type",
        "player_key",
        "player_urn",
        "resolved_player",
        "player_overview",
        "candidates",
        "served_from"
      ],
      "properties": {
        "skill_card": {
          "type": "object"
        },
        "structured_retrospective": {
          "type": "object",
          "required": [
            "content_type",
            "historical_perspective",
            "player_key",
            "name",
            "identity_mapping_status",
            "provider_ids",
            "observed_appearance_count",
            "observed_opponents",
            "observations",
            "unsupported_fields",
            "grounding"
          ]
        },
        "original_editorial": {
          "type": [
            "object",
            "null"
          ]
        },
        "content_type": {
          "enum": [
            "structured_retrospective",
            "original_editorial_with_structured_retrospective"
          ]
        },
        "player_key": {
          "type": "string"
        },
        "player_urn": {
          "type": [
            "string",
            "null"
          ]
        },
        "resolved_player": {
          "$ref": "#/$defs/Entity"
        },
        "player_overview": {
          "type": "object",
          "required": [
            "player_key",
            "name",
            "provider_ids",
            "identity_mapping_status"
          ]
        },
        "candidates": {
          "type": "array",
          "minItems": 1,
          "maxItems": 1
        },
        "served_from": {
          "const": "final_archive"
        }
      },
      "allOf": [
        {
          "if": {
            "required": [
              "content_type"
            ],
            "properties": {
              "content_type": {
                "const": "original_editorial_with_structured_retrospective"
              }
            }
          },
          "then": {
            "required": [
              "original_editorial"
            ],
            "properties": {
              "original_editorial": {
                "type": "object",
                "minProperties": 1
              }
            }
          }
        }
      ]
    }
  ],
  "$defs": {
    "ArchiveMetadata": {
      "type": "object",
      "required": [
        "mode",
        "version",
        "status",
        "competition",
        "competition_status",
        "live",
        "snapshot_as_of",
        "capability_status",
        "provenance",
        "missing_capabilities",
        "notes"
      ],
      "properties": {
        "mode": {
          "const": "final_archive"
        },
        "version": {
          "type": "string",
          "enum": [
            "world-cup-2026-final-v2",
            "world-cup-2026-final-v3"
          ]
        },
        "status": {
          "type": "string",
          "enum": [
            "hit",
            "miss",
            "unavailable",
            "error"
          ],
          "description": "hit = an immutable archived row was served. unavailable/error = nothing was served; see coverage.reason_code. A `miss` never reaches the public surface."
        },
        "competition": {
          "const": "FIFA World Cup 2026"
        },
        "competition_status": {
          "const": "completed"
        },
        "live": {
          "const": false
        },
        "snapshot_as_of": {
          "type": [
            "string",
            "null"
          ]
        },
        "source_observed_at": {
          "type": [
            "string",
            "null"
          ]
        },
        "content_created_at": {
          "type": [
            "string",
            "null"
          ]
        },
        "timestamp_semantics": {
          "type": "string"
        },
        "capability_status": {
          "type": "string"
        },
        "provenance": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "missing_capabilities": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "notes": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "response_sha256": {
          "type": "string",
          "pattern": "^[0-9a-f]{64}$"
        },
        "source_manifest_sha256": {
          "type": "string",
          "pattern": "^[0-9a-f]{64}$"
        },
        "request_identity_sha256": {
          "type": "string",
          "pattern": "^[0-9a-f]{64}$"
        },
        "reason_code": {
          "type": "string",
          "enum": [
            "fixture_selector_required",
            "fixture_ambiguous",
            "fixture_not_found",
            "player_selector_required",
            "player_ambiguous",
            "player_not_found",
            "entity_selector_required",
            "entity_ambiguous",
            "entity_not_found",
            "unsupported_parameter",
            "archive_row_missing",
            "archive_error"
          ]
        }
      }
    },
    "Coverage": {
      "type": "object",
      "required": [
        "schema_version",
        "status",
        "reason",
        "scope",
        "mode",
        "source_provenance",
        "population_count",
        "eligible_count",
        "included_count",
        "excluded_count",
        "exclusion_reasons",
        "unsupported_fields"
      ],
      "properties": {
        "schema_version": {
          "const": "worldcup-storefront-coverage-v1"
        },
        "status": {
          "type": "string",
          "enum": [
            "complete",
            "partial",
            "unavailable",
            "error"
          ]
        },
        "reason": {
          "type": "string",
          "minLength": 1
        },
        "scope": {
          "const": "completed_tournament_archive"
        },
        "mode": {
          "const": "historical"
        },
        "source_provenance": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "population_count": {
          "type": [
            "integer",
            "null"
          ],
          "minimum": 0,
          "description": "Null means the legacy response did not record this count; null is never equivalent to zero."
        },
        "eligible_count": {
          "type": [
            "integer",
            "null"
          ],
          "minimum": 0
        },
        "included_count": {
          "type": [
            "integer",
            "null"
          ],
          "minimum": 0
        },
        "excluded_count": {
          "type": [
            "integer",
            "null"
          ],
          "minimum": 0
        },
        "exclusion_reasons": {
          "type": "object",
          "additionalProperties": {
            "type": "integer",
            "minimum": 0
          }
        },
        "unsupported_fields": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "reason_code": {
          "type": "string",
          "enum": [
            "fixture_selector_required",
            "fixture_ambiguous",
            "fixture_not_found",
            "player_selector_required",
            "player_ambiguous",
            "player_not_found",
            "entity_selector_required",
            "entity_ambiguous",
            "entity_not_found",
            "unsupported_parameter",
            "archive_row_missing",
            "archive_error"
          ],
          "description": "Machine-readable cause, present whenever status is unavailable or error. Request-side codes (fixture_*/player_*/entity_*/unsupported_parameter) mean the caller can fix the request; the gateway answers them with HTTP 400 (missing/ambiguous/unsupported) or 404 (not_found). archive_row_missing (HTTP 503) and archive_error (HTTP 502) are on our side. None of these calls is billed."
        },
        "accepted_fields": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "The request fields this endpoint accepts, echoed on unserved responses so an agent can self-correct."
        }
      }
    },
    "Entity": {
      "type": "object",
      "properties": {
        "_id": {
          "type": [
            "string",
            "null"
          ]
        },
        "@id": {
          "type": [
            "string",
            "null"
          ]
        },
        "player_key": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "provider_ids": {
          "$ref": "#/$defs/ProviderIds"
        },
        "provider_id_aliases": {
          "type": "object",
          "additionalProperties": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "identity_mapping_status": {
          "type": "string",
          "enum": [
            "canonical",
            "official_reconciled",
            "provider_only",
            "quarantined"
          ]
        },
        "official_registration": {
          "$ref": "#/$defs/OfficialRegistrationPlayer"
        }
      }
    },
    "OfficialRegistrationPlayer": {
      "type": "object",
      "required": [
        "status",
        "source_url",
        "source_sha256",
        "published_at",
        "source_page",
        "team_name",
        "fifa_team_code",
        "jersey_number",
        "player_name_raw",
        "birth_date",
        "position_code",
        "warnings",
        "canonical_birth_date_conflict"
      ],
      "properties": {
        "status": {
          "const": "verified_final_published_snapshot"
        },
        "source": {
          "const": "FIFA"
        },
        "source_url": {
          "type": "string",
          "format": "uri"
        },
        "source_sha256": {
          "type": "string",
          "pattern": "^[0-9a-f]{64}$"
        },
        "published_at": {
          "type": "string",
          "format": "date-time"
        },
        "source_page": {
          "type": "integer",
          "minimum": 1,
          "maximum": 48
        },
        "team_name": {
          "type": "string"
        },
        "fifa_team_code": {
          "type": "string"
        },
        "jersey_number": {
          "type": "integer",
          "minimum": 1,
          "maximum": 26
        },
        "player_name_raw": {
          "type": "string"
        },
        "first_names_raw": {
          "type": "string"
        },
        "last_names_raw": {
          "type": "string"
        },
        "shirt_name_raw": {
          "type": "string"
        },
        "birth_date": {
          "type": "string",
          "format": "date"
        },
        "position_code": {
          "enum": [
            "GK",
            "DF",
            "MF",
            "FW"
          ]
        },
        "club_raw": {
          "type": [
            "string",
            "null"
          ]
        },
        "height_cm": {
          "type": "integer"
        },
        "international_caps_as_reported": {
          "type": "integer"
        },
        "international_goals_as_reported": {
          "type": "integer"
        },
        "warnings": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "canonical_birth_date": {
          "type": [
            "string",
            "null"
          ]
        },
        "canonical_birth_date_conflict": {
          "type": "boolean"
        },
        "scope_note": {
          "type": "string"
        }
      }
    },
    "ProviderIds": {
      "type": "object",
      "additionalProperties": {
        "type": [
          "string",
          "integer",
          "null"
        ]
      }
    },
    "ResponseBase": {
      "type": "object",
      "required": [
        "archive",
        "coverage",
        "warnings"
      ],
      "properties": {
        "archive": {
          "$ref": "#/$defs/ArchiveMetadata"
        },
        "coverage": {
          "$ref": "#/$defs/Coverage"
        },
        "warnings": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      }
    }
  }
}