{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/lumify-ai/json-schema/lumify-ai-player-schema.json",
  "title": "Player",
  "description": "Directory identity for one player. Shared keys on every sport; null means\nunknown, not 'wrong sport'. Sport-named metrics do not live here —\ntennis ranking is ``rankings`` (null on every other sport). Tennis\n``/stats`` also exposes ``ranking`` / ``ranking_points`` on the tennis\nplayer block.",
  "x-generated": "2026-10-31",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/lumify-ai-openapi.json#/components/schemas/Player",
  "properties": {
    "id": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "title": "Id",
      "description": "Lumify player ID."
    },
    "slug": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Slug",
      "description": "URL-safe unique slug."
    },
    "full_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Full Name",
      "description": "Display name."
    },
    "first_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "First Name"
    },
    "last_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Last Name"
    },
    "sport": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Sport",
      "description": "Sport slug, e.g. mlb, tennis, nfl."
    },
    "country_code": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Country Code",
      "description": "ISO 3166-1 alpha-3 country code."
    },
    "birthdate": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Birthdate",
      "description": "YYYY-MM-DD date of birth."
    },
    "position": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Position",
      "description": "Roster position abbreviation when the sport has one (e.g. C, P, SS for MLB; QB, WR for NFL). Null for tennis and when not yet ingested."
    },
    "handedness": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Handedness",
      "description": "left | right | switch. Meaning is sport-specific (bats for MLB, shoots for NHL, playing hand for tennis). Null when unknown."
    },
    "height_cm": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "title": "Height Cm",
      "description": "Height in centimetres. Null when not ingested."
    },
    "weight_kg": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "title": "Weight Kg",
      "description": "Weight in kilograms. Null when not ingested."
    },
    "rankings": {
      "anyOf": [
        {
          "$ref": "#/$defs/PlayerRankings"
        },
        {
          "type": "null"
        }
      ],
      "description": "Sport ranking block. Tennis: {singles, points} from ATP/WTA standings. Null for every other sport. Tennis /stats also exposes ranking / ranking_points on the tennis player block."
    },
    "current_team_id": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "title": "Current Team Id",
      "description": "Lumify team ID when the player is on a club roster. Null for tennis."
    },
    "current_team_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Current Team Name",
      "description": "Current team display name. Null for tennis."
    },
    "is_active": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "title": "Is Active",
      "description": "False when deactivated or retired."
    },
    "retired_at": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Retired At",
      "description": "YYYY-MM-DD retirement date when known."
    },
    "image_url": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Image Url",
      "description": "Lumify media URL for the player headshot (https://lumify.ai/media/players/{sport}/{id}.{ext}). Null until the sport's headshot/enrichment job. Never a vendor CDN."
    }
  },
  "additionalProperties": true,
  "type": "object",
  "$defs": {
    "PlayerRankings": {
      "properties": {
        "singles": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Singles",
          "description": "ATP/WTA singles ranking. Tennis only."
        },
        "points": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "title": "Points",
          "description": "ATP/WTA ranking points. Tennis only."
        }
      },
      "additionalProperties": true,
      "type": "object",
      "title": "PlayerRankings"
    }
  }
}