---
title: The week param is documented for from-plays columns and silently ignored
type: task
status: cancelled
description: >-
  docs/data-views-system.md advertises a week param on *_from_plays columns that nothing on that
  path reads, so setting it silently returns unfiltered results. Needs a reject-or-translate
  decision, not just a docs edit.
base_uri: user:task/league/data-views/fix-unread-week-param-on-from-plays-columns.md
created_at: '2026-07-31T21:52:54.448Z'
entity_id: 46205d57-71b2-412e-ab3f-891b73d2aef4
finished_at: '2026-10-19T18:28:18.450Z'
observations:
  - ████████████████████████████████████████████████
owner_identity_uri: █████████████████████████
priority: Medium
public_read: true
relations:
  - relates [[█████████████████████-█████████-████-█████-████-████-█████-████████████]]
  - relates [[█████████████████████-██████████████-████-████-█████-████████████]]
tags:
  - user:tag/league-xo-football.md
updated_at: '2026-10-19T18:28:18.450Z'
visibility_analyzed_at: '2026-11-05T23:48:52.085Z'
---

# The `week` param is documented for from-plays columns and silently does nothing

`docs/data-views-system.md` advertises `week` as a column param for the `*_from_plays` family. Nothing on that path reads it. A user who sets it gets a silently unfiltered result — no error, no warning, a wrong answer that looks right.

Surfaced during [[█████████████████████-█████████-████-█████-████-████-█████-████████████]], which established the fact while fixing an adjacent defect but scoped this out of its own change.

## Evidence

**The docs advertise it twice**, both on from-plays columns, in the § Column Configuration Patterns block:

- `docs/data-views-system.md:238` — `week: [1, 2, 3, 4], // Week range` on `player_fantasy_points_from_plays`
- `docs/data-views-system.md:249` — `week: { dynamic_type: "current_week" }` on `player_rushing_yards_from_plays`

**Nothing reads it.** `nfl_week_id` is the canonical week param for this family and is a member of `nfl_plays_column_params`; `params.week` is not read on the from-plays path. Stated directly in the source comment landed by commit `ff1e538c4` (`libs-server/data-views/get-stats-column-param-key.mjs`), which excludes `week` from the alias key on exactly that ground: two from-plays columns differing only by `week` genuinely resolve to the same query.

**How it got this way.** Commit `64a28f9dc` replaced `year`/`week`/`seas_type` with the composite `nfl_week_id` in the params registry. `year` survived as a user-facing param resolved a layer up in `resolve_params_contribution`; `week` did not survive anywhere, but the documentation examples were never updated.

## The decision this needs

Silently dropping an unread param is the failure mode, not the docs line. Pick one:

1. **Reject it.** Have the validator refuse `week` on the from-plays family, pointing at `nfl_week_id`. Loudest and safest, but it breaks any saved view carrying the key.
2. **Migrate it.** Translate an inbound `week` to the equivalent `nfl_week_id` values. There is precedent — `scripts/migrate-data-views-single-nfl-week.mjs` and `libs-shared/data-views-nfl-week-migration.mjs` already do exactly this rewrite for `year`/`week`/`seas_type` on saved views, and `docs/data-views-system.md:304` says the server keeps a fallback path for views still carrying those keys. **Check whether that fallback already handles `week` before assuming it does not** — if it does, this is a docs-only fix and the "silent no-op" framing is wrong for saved views, though still right for a hand-authored API request.
3. **Docs only.** Remove the examples. Cheapest, and leaves the silent drop in place for anyone calling the API directly.

Option 2 conditional on that check, falling back to option 1, is the recommendation. Option 3 alone leaves the actual defect.

## Scope note

Whatever is chosen, the general problem is wider than `week`: an unlisted param on a from-plays column is accepted and ignored. That is the same non-strict-schema class as the live injection surface in [[█████████████████████-██████████████-████-████-█████-████████████]]. Do not fix the general case here — that task owns the boundary — but expect the two to converge.

## Plan

- [ ] **Check whether the saved-view fallback already resolves `week`**
  - Files: `libs-shared/data-views-nfl-week-migration.mjs`, `scripts/migrate-data-views-single-nfl-week.mjs`, and the server fallback path referenced at `docs/data-views-system.md:304`
  - Verify: a from-plays column with `week: [1,2]` and no `nfl_week_id`, run through the query builder — does the emitted SQL carry a week predicate? Record the answer as an observation. It selects the option below.

- [ ] **Apply the chosen handling**
  - Reject at the validator, or translate to `nfl_week_id`, per the check above.
  - Verify: a spec asserting the behaviour, including the case of `week` alongside an explicit `nfl_week_id`.

- [ ] **Fix the documentation**
  - File: `docs/data-views-system.md:238` and `:249`
  - Replace the `week` examples with `nfl_week_id`, and state which params the from-plays family actually reads.
  - Verify: no remaining example advertises a param the path does not read.

- [ ] **Sweep for other unread advertised params**
  - The same registry change (`64a28f9dc`) could have orphaned others. Cross-check every param in the § Column Configuration Patterns examples against what the corresponding path reads.
  - Verify: each documented param has a reader, or is removed.