fix(v2-ingestion): harden LBA/BCL snapshot contract for public data

README.md

@@ -156,8 +156,14 @@ Each file must be a JSON object:
 
 Validation is strict:
 - unknown fields are rejected
-- required fields must exist
-- `snapshot_date` and `birth_date` must be `YYYY-MM-DD`
+- required fields must exist:
+  - `competition_external_id`, `competition_name`, `season`
+  - `team_external_id`, `team_name`
+  - `player_external_id`, `full_name`
+  - core stats (`games_played`, `minutes_per_game`, `points_per_game`, `rebounds_per_game`, `assists_per_game`, `steals_per_game`, `blocks_per_game`, `turnovers_per_game`, `fg_pct`, `three_pt_pct`, `ft_pct`)
+- optional player bio/physical fields:
+  - `first_name`, `last_name`, `birth_date`, `nationality`, `height_cm`, `weight_kg`, `position`, `role`
+- when `birth_date` is provided it must be `YYYY-MM-DD`
 - numeric fields must be numeric
 - invalid files are moved to failed directory
 
@@ -304,6 +310,7 @@ Notes:
 - season is configured by `EXTRACTOR_LBA_SEASON_LABEL`
 - parser supports payload keys: `records`, `data`, `players`, `items`
 - normalization supports nested `player` and `team` objects with common stat aliases (`gp/mpg/ppg/rpg/apg/spg/bpg/tov`)
+- public-source player bio/physical fields are often incomplete; extractor allows them to be missing and emits `null` for optional fields
 - no live HTTP calls in tests; tests use fixtures/mocked responses only
 
 ### BCL extractor assumptions and limitations (MVP)
@@ -316,6 +323,7 @@ Notes:
 - season is configured by `EXTRACTOR_BCL_SEASON_LABEL`
 - parser supports payload keys: `records`, `data`, `players`, `items`
 - normalization supports nested `player` and `team` objects with common stat aliases (`gp/mpg/ppg/rpg/apg/spg/bpg/tov`)
+- public-source player bio/physical fields are often incomplete; extractor allows them to be missing and emits `null` for optional fields
 - no live HTTP calls in tests; tests use fixtures/mocked responses only
 
 ## Migration and Superuser Commands