Mandatory /retrieve-date model doesn't fit age-band-only providers; monitoredPeriod=0 is the only workaround

[hdamker]

Problem description

/check and /retrieve-date are mandatory; /retrieve-age-band is optional (501 NOT_IMPLEMENTED), documented as "an alternative ... for providers that do not expose the exact SIM swap date" (#285).

But /retrieve-date's only defined way to withhold information is the null + monitoredPeriod mechanism, and that only fires for swaps older than the provider's monitored window. It has no way to express "I categorically do not disclose the exact date, only age bands."

A provider whose policy is age-band-only cannot express that through /retrieve-date's current mandatory model without either:

• returning the exact date anyway (defeats the reason it wanted /retrieve-age-band in the first place), or
• setting monitoredPeriod to 0 (or another degenerate value) so it always returns null — using a retention-window field to fake "not offered," since /retrieve-date has no 501 of its own.

The mandatory/optional split assumes /retrieve-age-band is a genuine alternative, but nothing in the spec lets a provider actually commit to offering only that alternative.

Possible evolution

Make /retrieve-date optional (501 NOT_IMPLEMENTED), symmetric with /retrieve-age-band, so an age-band-only provider can say so directly instead of gaming monitoredPeriod. #285 already raised this as an "alternative solution" and deferred it as a breaking, next-major change; this issue tracks that decision explicitly rather than letting it drop.

Alternative solution

Keep /retrieve-date mandatory, but document monitoredPeriod: 0 (or another explicit sentinel) as the sanctioned way to declare "exact date never disclosed," instead of leaving it an implicit hack.

Additional context

• Raised while reviewing fix: resolve r4.1 release review findings (#285, #286, #287, #289) #290, which touched the /retrieve-age-band optionality wording from sim-swap description overclaims optionality for /check and /retrieve-date #285.
• Related: SimSwapAgeBand schema can't express valid limits for the 111 sentinel (S-310/S-311 in #276) #277 (schema for this operation's sentinel value).
• This release cycle targets sim-swap 2.2.0 (rc); making /retrieve-date optional is a breaking change and would require a 3.0.0 major bump.

[yyeAduna]

One note on the framing: I’m not sure this really depends on /retrieve-age-band. A CSP that cannot disclose exact swap dates is in essentially the same position with or without the age-band operation; #285 just makes that tension more explicit. Making /retrieve-date optional in 3.0.0 seems to stand on its own.

On the interim monitoredPeriod: 0 option, I'd be cautious:

• 0 would also give the field a different meaning: "exact date not disclosed" instead of "the period in which no swap was observed."

• There is also a compatibility risk: consumers that interpret latestSimChange: null as “no recent swap” without checking monitoredPeriod could treat every number from such a CSP as clean, including numbers with a recent swap. That creates a fail-open risk

If this is still adopted for 2.2.0, the meaning of 0 should be explicit, and consumers MUST check monitoredPeriod before interpreting null.

[hdamker]

The original issue is fixed by #292.

The current model from 2.1.0 stays unchanged, but with the clarification for latestSimChange done in #290 that "The value is null when the provider cannot return it for privacy reasons (the monitoredPeriod mechanism applies)." (BTW: it is obviously not a date)