Strict datetime validation diverges from spec/reference on two edges: year 0000 and max length

[jacoblapenna]

Hi! I've been writing spec-conformance tests for an AT Protocol project I'm working on, and this SDK is what I cross-check my results against, as it's the most mature Python implementation of the protocol, so disagreeing with it is my cue to go digging. On two datetime edges we disagreed, and after arbitrating against the Lexicon spec and the reference datetime.ts, it turned out these look like rare cases where the divergence is on this side (same digging that surfaced #695 and #696). Filing as an issue rather than a PR because the fix involves a design choice I didn't want to make for you.

1. Year 0000 is rejected (spec lists it as a preferred valid example)

TypeAdapter(DateTime).validate_python('0000-01-01T00:00:00.000Z', context={'strict_string_format': True})
# ValidationError: Invalid datetime: year 0 is out of range

The Lexicon spec's valid examples include 0000-01-01T00:00:00.000Z under "preferred", and the reference datetime.ts accepts years 0000–9999, rejecting only datetimes that normalize to a negative year (e.g. 0000-01-01T00:00:00+01:00, which is in the interop invalid vectors). The root cause is structural: validate_datetime finishes with datetime.fromisoformat, and Python's datetime.MINYEAR is 1, so year 0000 can't even be represented. A fix probably means either special-casing year 0000 (e.g. substituting a stand-in leap year for the parse, plus an explicit check that an offset doesn't normalize below the year floor) or hand-rolling the semantic checks. Happy to send a PR for whichever direction you prefer, if any (in practice, this probably only bites by rejecting a joke post from year 0000 or something).

2. No maximum length — a design question rather than a clear-cut bug

The reference implementation rejects any datetime longer than 64 characters: datetime.ts#L329-L330. Unlike item 1, this rule appears nowhere in the Lexicon spec text — it exists only in the reference code — so it's genuinely your policy call: should strict mode here conform to the spec as written, or to the de-facto behavior of the network (which runs the reference)? Today validate_datetime has no length check at all, so e.g. a 65-char datetime with a 44-digit fractional-seconds part passes strict validation here but is rejected by the reference, and therefore by live PDS/relay/AppView infrastructure.

If you'd like to match the reference, the exact change I'd be happy to submit as a PR:

• MAX_DATETIME_LENGTH: int = 64 alongside the other length constants in string_formats.py
• an early check in validate_datetime: if len(v) > MAX_DATETIME_LENGTH: raise ValueError(...) with a message mirroring the reference's ("too long (64 chars max)")
• parametrized tests pinning the 64/65-char boundary

One heads-up either way: adding the cap means strict mode starts rejecting over-long datetimes it currently accepts. That behavior change is exactly why I'm asking first rather than sending the PR directly.

Thanks again for the library!

[jacoblapenna]

Quick follow-up with upstream context that may affect the design choice here: bluesky-social/atproto#4758 (open, by a core engineer) is actively reworking datetime validation:

• It drops the "normalizes to a negative year" rule, accepting any RFC 3339 / ISO 8601 / WHATWG-compatible datetime within 24h of the year-0000/9999 boundaries. The 0000-01-01T00:00:00+01:00 example I cited above is removed from the invalid vectors by that PR and would become valid.
• The 64-char cap is untouched by it, so item 2 stands as-is (I've asked upstream whether the cap should be documented in the spec text, which would settle the policy question here either way).

Two implications for item 1 if #4758 merges:

1. The Python situation gets slightly harder: not just bare 0000-…Z, but also offset forms resolving to just before year 0000 (and just after 9999) become legal, and none of those are representable by datetime/fromisoformat (MINYEAR/MAXYEAR are 1/9999). A fix that special-cases "year == 0000, no boundary crossing" would need loosening again later.
2. That tilts the design choice toward hand-rolled string-level semantic checks (month/day/time ranges validated directly, no round-trip through datetime) — it sidesteps MINYEAR entirely and is robust to whichever way upstream lands. Alternatively, it's perfectly reasonable to just wait for #4758 to resolve before touching item 1.

I've also suggested upstream that vectors be added for these edges, so the interop files would catch this class of divergence for every implementation going forward.