---
type: Architecture Decision
title: Queryable raster periods
description: Declare safe exact and cumulative on-demand raster periods in Channel.
tags: [rendering, raster, temporal, channel]
visibility: public
---

# Rule

An on-demand raster exposes a period control only when its
[Channel](/catalog/channel.md) declares a validated `period_selection`
capability. `annual-range-v1` defines a bounded consecutive year range, whether
the provider can return one cumulative result, and a valid default period.

The current selection is viewer-local and keyed by Layer plus Channel. It does
not mutate Layer style, Channel metadata, palettes, or the published map.

# Request boundary

The browser sends one semantic `period_id`: an exact declared year or `all`.
It never sends provider query names or arbitrary start/end values. The tile
proxy validates access to the bound Layer, Channel, and period, then translates
that identifier into the provider-specific request. Cache identity includes the
period automatically through the tile URL. When an encoded provider tile keeps
all periods in one immutable image, Channel may additionally declare a validated
`value_filter`; the renderer masks the selected raw pixel channel locally while
the proxy still authorizes the semantic period.

`all` is shown only when the provider itself declares a meaningful cumulative
result. GeoLama does not merge or sum raster pixels in the browser. A local
exact-period mask is allowed only when its pixel channel and year mapping are
provider-declared and validated; arbitrary client expressions are not accepted.
A cumulative-only dataset without exact periods does not receive a misleading
year selector.

# Administration

Channel settings may narrow the published range, enable or disable cumulative
`all`, and choose a valid default only for an adapter that already declares the
capability. Provider-specific database validation retains the immutable physical
bounds, so administration cannot claim unavailable years or enable the contract
for an incompatible proxy.

# Checklist

1. Declare physical provider bounds separately from the editable published range.
2. Validate the capability in the client render contract and the database.
3. Validate `period_id` again in the authorized tile proxy.
4. Keep exact periods and cumulative results scientifically distinct in labels.
5. Verify local persistence, invalid preference cleanup, cache separation, and
   the default period.
6. For encoded time-series tiles, verify exact and cumulative upstream bytes,
   document the pixel channel, and test the exact-period mask visually.