Audit and update stat models for MLB payload fields and aliases #339

Summary

We should systematically audit stat model fields against live MLB Stats API responses and update model aliases/fields where the API payload has changed or where our models are currently not mapping returned keys correctly.

This is a tracking issue for discrepancies discovered during the audit. The goal is to distinguish:

• MLB fields that are legitimately omitted for a given stat type
• MLB fields that are returned but are not represented by our model
• fields that exist in the model but use the wrong alias/casing
• parsed values that do not match the raw MLB response

Confirmed findings so far

Hitting

Audited 2025 season and seasonAdvanced for Aaron Judge, Shohei Ohtani, and Juan Soto.

• 195 fields matched correctly
• 0 model-missing fields
• 0 parse failures
• 0 mismatches
• flyOuts is omitted by MLB from the standard season payload but is present/populated in seasonAdvanced

No confirmed hitting model changes are needed from this audit so far.

Pitching — SimplePitchingSplit

The live season payload returns these keys, but the current model aliases do not match them:

• groundOuts -> groundouts
• airOuts -> airouts
• groundOutsToAirouts -> groundouts_to_airouts

Expected aliases:

groundouts: Optional[int] = Field(default=None, alias="groundOuts")
airouts: Optional[int] = Field(default=None, alias="airOuts")
groundouts_to_airouts: Optional[str] = Field(
    default=None,
    alias="groundOutsToAirouts",
)

Pitching — AdvancedPitchingSplit

The live seasonAdvanced payload returns these keys, but the current model aliases do not match them:

• strikesoutsToWalks -> strikeouts_to_walks
• flyOuts -> flyouts
• popOuts -> popouts
• lineOuts -> lineouts
• groundOuts -> groundouts
• flyBallPercentage -> flyball_percentage

Note: MLB currently appears to return strikesoutsToWalks with the extra s; the model should reflect the actual API payload unless further audit shows multiple spellings are in use.

Audit results for pitching sample

2025 season and seasonAdvanced were checked for Tarik Skubal, Paul Skenes, and Logan Gilbert.

Overall:

• PASS: 327
• MLB OMITTED: 42
• MODEL MISSING: 27
• PARSE FAILURE: 0
• MISMATCH: 0
• REQUEST ERROR: 0

The 27 MODEL MISSING rows collapse to 9 unique alias problems repeated across the three pitchers.

Next steps

• Continue audit with fielding stat types
• Audit additional hitting/pitching stat types (career, careerAdvanced, yearByYear, etc.)
• Record newly discovered payload/model discrepancies here
• Fix confirmed alias/field issues in a focused change after the audit has enough coverage
• Add deterministic regression tests for confirmed issues using representative payloads rather than live MLB API calls in CI

Scope

This issue is for stat-model schema/alias maintenance discovered through the audit. Live audit tooling itself does not need to be committed to the project.