hoopscout/docs/provider-normalization.md

Provider Normalization Contract

HoopScout ingestion consumes provider data through a normalized, provider-agnostic contract defined in:

• apps/providers/contracts.py
• apps/providers/interfaces.py

Contract scope

Adapters must return only normalized entities used by ingestion:

• players
• competitions
• teams
• seasons
• player_stats
• player_careers
• optional cursor

Raw provider response structures must remain inside apps/providers (client/adapter/mapping code).
ExternalMapping.raw_payload is used only for diagnostics and troubleshooting.

Current balldontlie assumptions (MVP)

• Source scope is NBA-centric.
• Competition is normalized as a single NBA competition (competition-nba).
• API contract source is https://www.balldontlie.io/openapi.yml (server https://api.balldontlie.io, NBA endpoints under /nba/v1/*).
• Team country is not reliably available in source payloads and is normalized to null.
• Player nationality/birth/physical details are not available in player list payloads and are normalized to null (except fields explicitly present).
• Configured seasons are normalized from PROVIDER_BALLDONTLIE_SEASONS; the highest configured season is marked is_current=true.
• Stats ingestion uses /nba/v1/stats with seasons[] and cursor pagination.
• Advanced metrics (usage_rate, true_shooting_pct, player_efficiency_rating) are currently unavailable from this source path and normalized to null.

Domain rules vs provider assumptions

• Domain rules live in ingestion/domain services and models.
• Provider assumptions live only in adapter/mapping modules.
• New providers must map to the same normalized contract and should not require ingestion logic changes.