developmentseed / developmentseed/titiler-covjson

Track upstream covjson-pydantic reduced-precision datetime coercion (KNMI/covjson-pydantic#34)

Open
#15 0 comments 0 reactions 1 assignee Claimed by @chuckwondo View on GitHub
Dominant language
Python
Stars
1
Forks
1
Avg merge
2d 1h
Merged PRs (30d)
12

Description

## Summary

`covjson-pydantic`'s `ValuesAxis[AwareDatetime]` mishandles reduced-precision
time values that the CoverageJSON spec explicitly allows. For a Gregorian
`TemporalRS`, four of the five spec-valid lexical forms are broken
(`covjson-pydantic` 0.8.0):

| `t` value | spec-valid? | covjson-pydantic 0.8.0 behavior |
| --- | --- | --- |
| `"2010"` | yes | silently coerced to `1970-01-01T00:33:30Z` |
| `"+002010"` | yes | silently coerced to a ~1970 timestamp |
| `"2010-06"` | yes | rejected (`ValidationError`) |
| `"2010-06-15"` | yes | rejected (`ValidationError`) |
| `"2010-06-15T00:00:00Z"` | yes | parses correctly |

The silent coercion is a data-corruption hazard: a valid-looking Coverage
round-trips to wrong data (a year becomes a 1970 timestamp).

## Background

Per OGC 21-069r2 (Section 9.5.2), reduced-precision dates such as `"2016"` are
**explicitly valid**, and a client SHOULD interpret them at that reduced
precision. So the fix must **preserve the lexical string**, not reject it -- a
Python `datetime` cannot hold reduced precision, and round-trip fidelity is the
library's core contract. The coercion happens in both strict and lax pydantic
modes, so `strict=True` alone does not fix it.

Upstream issue: KNMI/covjson-pydantic#34 (filed 2026-06-16). It lays out the
problem, spec quotes, the behavior table above, a minimal reproducer, the root
cause, and candidate solutions for the maintainers to choose; no PR yet.

## Current workaround in this repo

The playground round-trip tests adapt year-only `t` values to full RFC 3339
timestamps so they are not silently corrupted:

- `TestPlaygroundGridTiled` and `TestPlaygroundPolygonSeries` in
`tests/test_playground_roundtrip.py`.
- A module-level note in the same file documents the adaptation.

## When upstream releases

- [ ] Drop the timestamp adaptations and use the verbatim playground year
values in `TestPlaygroundGridTiled` and `TestPlaygroundPolygonSeries`.
- [ ] Remove the module-level upstream note in `tests/test_playground_roundtrip.py`.
- [ ] Bump the `covjson-pydantic` pin to the fixed release.

## References

- Upstream issue: https://github.com/KNMI/covjson-pydantic/issues/34
- Related upstream issue (strict-mode toggle, largely independent):
https://github.com/KNMI/covjson-pydantic/issues/4
- Spec: OGC 21-069r2, Section 9.5.2 (Temporal Reference System)

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.