valuation-request.v1.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://github.com/amethyst/amethyst-api/schemas/valuation-request.v1.schema.json",
  "title": "Amethyst Engine POST /valuation/calculate (Draft upstream v1)",
  "description": "Flat valuation context forwarded by AmethystDraft from leagues/rosters or Activity #9 fixtures. Mirror of Draft `apps/api/schemas/valuation-request.v1.schema.json` when present. player_id = MLB Stats API person id string (externalPlayerId).",
  "type": "object",
  "required": [
    "roster_slots",
    "scoring_categories",
    "total_budget",
    "drafted_players"
  ],
  "properties": {
    "roster_slots": {
      "type": "array",
      "minItems": 1,
      "items": {
        "$ref": "#/$defs/rosterSlot"
      }
    },
    "scoring_categories": {
      "type": "array",
      "minItems": 1,
      "items": {
        "$ref": "#/$defs/scoringCategory"
      }
    },
    "total_budget": {
      "type": "number",
      "exclusiveMinimum": 0
    },
    "num_teams": {
      "type": "integer",
      "minimum": 1
    },
    "league_scope": {
      "type": "string",
      "enum": [
        "Mixed",
        "AL",
        "NL"
      ]
    },
    "drafted_players": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/draftedPlayer"
      }
    },
    "schema_version": {
      "type": "string",
      "description": "Fixture / contract version from Draft (e.g. 1.0.0). engine also accepts camelCase schemaVersion."
    },
    "schemaVersion": {
      "type": "string"
    },
    "league_id": {
      "type": "string",
      "description": "Optional stable league id from Draft; echoed in valuation `context_v2.scope.league_id`."
    },
    "checkpoint": {
      "type": "string",
      "description": "e.g. pre_draft | after_pick_10 | after_pick_50 | after_pick_100 | after_pick_130"
    },
    "budget_by_team_id": {
      "type": "object",
      "additionalProperties": {
        "type": "number",
        "minimum": 0
      }
    },
    "scoring_format": {
      "type": "string",
      "enum": [
        "5x5",
        "6x6",
        "points"
      ]
    },
    "hitter_budget_pct": {
      "type": "number"
    },
    "pos_eligibility_threshold": {
      "type": "number",
      "description": "Reserved / informational only in v1 — engine does not compute games-by-position from Mongo. Use position_overrides for explicit eligibility."
    },
    "position_overrides": {
      "type": "array",
      "description": "Per-player eligibility from Draftroom (min-games rules). Replaces Mongo position/positions for slot fitting, baseline scarcity, replacement_slots_v2, team-adjusted value, and scarcity analysis.",
      "items": {
        "$ref": "#/$defs/positionOverrideEntry"
      }
    },
    "injury_overrides": {
      "type": "array",
      "description": "Optional per-player injury severity from Draftroom (MLB roster / IL). Overrides Mongo catalog injurySeverity for the baseline injury pass only.",
      "items": {
        "$ref": "#/$defs/injuryOverrideEntry"
      }
    },
    "strict_scoring_categories": {
      "type": "boolean",
      "description": "When true, valuation fails if scoring_categories includes names not modeled in v1 baselines. Default false: unsupported names yield scoring_category_warnings on the response."
    },
    "minors": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/teamBucket"
      }
    },
    "taxi": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/teamBucket"
      }
    },
    "deterministic": {
      "type": "boolean"
    },
    "seed": {
      "type": "number"
    },
    "player_ids": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1
      }
    },
    "eligible_player_ids": {
      "type": "array",
      "description": "Optional whitelist of catalog player ids in the valuation universe (after league_scope). Omit or empty = full scoped catalog.",
      "items": {
        "type": "string",
        "minLength": 1
      }
    },
    "excluded_player_ids": {
      "type": "array",
      "description": "Optional blacklist applied after league_scope and eligible_player_ids.",
      "items": {
        "type": "string",
        "minLength": 1
      }
    },
    "inflation_model": {
      "type": "string",
      "enum": [
        "global_v1",
        "surplus_slots_v1",
        "replacement_slots_v2"
      ],
      "description": "global_v1 = league-wide list rescale. surplus_slots_v1 = single replacement slice. replacement_slots_v2 = slot/position-aware replacement + surplus (official default when omitted)."
    },
    "pre_draft_rosters": {
      "description": "Keepers / pre-draft rosters: either a map team_id → rows, or an array of { team_id, players } (Draft BFF finalize payload).",
      "oneOf": [
        {
          "type": "object",
          "additionalProperties": {
            "type": "array"
          }
        },
        {
          "type": "array",
          "items": {
            "$ref": "#/$defs/teamBucket"
          }
        }
      ]
    },
    "user_team_id": {
      "type": "string",
      "description": "Optional team context for team_adjusted_value; defaults to team_1 when omitted."
    },
    "explain_valuation_rows": {
      "type": "boolean",
      "description": "When true, each valuations[] row may include valuation_explain (slot/replacement + pool context + baseline risk multipliers: age, depth, injury — informational only)."
    },
    "recommended_bid_soft_cap_ratio": {
      "type": "number",
      "minimum": 1,
      "maximum": 5,
      "description": "Optional: after smoothing, clamp recommended_bid to at most this multiple of auction_value (auction_value unchanged)."
    }
  },
  "$defs": {
    "positionOverrideEntry": {
      "type": "object",
      "required": ["player_id", "positions"],
      "additionalProperties": false,
      "properties": {
        "player_id": {
          "type": "string",
          "minLength": 1
        },
        "positions": {
          "type": "array",
          "minItems": 1,
          "items": {
            "type": "string",
            "minLength": 1
          }
        }
      }
    },
    "injuryOverrideEntry": {
      "type": "object",
      "required": ["player_id", "injury_severity"],
      "additionalProperties": false,
      "properties": {
        "player_id": {
          "type": "string",
          "minLength": 1
        },
        "injury_severity": {
          "type": "integer",
          "minimum": 0,
          "maximum": 3
        }
      }
    },
    "rosterSlot": {
      "type": "object",
      "required": [
        "position",
        "count"
      ],
      "properties": {
        "position": {
          "type": "string"
        },
        "count": {
          "type": "integer",
          "minimum": 1
        }
      },
      "additionalProperties": false
    },
    "scoringCategory": {
      "type": "object",
      "required": [
        "name",
        "type"
      ],
      "properties": {
        "name": {
          "type": "string"
        },
        "type": {
          "type": "string",
          "enum": [
            "batting",
            "pitching"
          ]
        }
      },
      "additionalProperties": false
    },
    "draftedPlayer": {
      "type": "object",
      "required": [
        "player_id",
        "name",
        "position",
        "team",
        "team_id"
      ],
      "properties": {
        "player_id": {
          "type": "string",
          "minLength": 1
        },
        "name": {
          "type": "string"
        },
        "position": {
          "type": "string"
        },
        "team": {
          "type": "string"
        },
        "team_id": {
          "type": "string"
        },
        "paid": {
          "type": "number",
          "minimum": 0
        },
        "positions": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "is_keeper": {
          "type": "boolean"
        },
        "roster_slot": {
          "type": "string"
        },
        "pick_number": {
          "type": "integer"
        }
      },
      "additionalProperties": false
    },
    "teamBucket": {
      "type": "object",
      "required": [
        "team_id",
        "players"
      ],
      "properties": {
        "team_id": {
          "type": "string"
        },
        "players": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/draftedPlayer"
          }
        }
      },
      "additionalProperties": false
    }
  }
}