ISO 8601 Durations

[bernot-dev]

Describe the bug
ISO 8601 durations were accidentally valid before #246 (although sometimes parsed incorrectly). Now they are rejected.

Steps to Reproduce

Validate an ISO 8601 duration, like P3Y6M4DT12H30M5S.

Expected behavior
ISO 8601 durations should be accepted and parsed correctly.

Actual behavior
ISO 8601 durations are rejected since #246, and potentially parsed incorrectly before then.

Additional context
The OpenAPI format registry refers to to RFC3339/ISO 8601 as the "official" spec.

[liggitt]

Hmm... this representation is so different from what was expected, so unlikely to have been parsed correctly, and the inability to parse ambiguous durations of year and month to concrete time.Duration makes me doubt this is reasonable to add support for

[fredbi]

When this code was first introduced neither openapi (v2) nor jsonschema did support duration.
So that was an addition based on common practice (iso durations never really took off: the format is so ugly…). Iso durations have been introduced by jsonschema draft 2020 IIRC.

This library should be extended to support modern jsonschema standardization. So yes we need to support this.

However - having tried some time ago a similar implementation - this is not as trivial as it seems because of the range and precision iso durations cover which don’t fit nicely with time.Duration. So we need to check for overflow.

[fredbi]

Thanks for opening this @bernot-dev — and thanks especially for #280, which is a lot more than a drive-by. This is squarely something we want: ISO 8601 / RFC 3339 duration support has been on the roadmap as we move strfmt toward the JSON Schema 2020-12 vocabulary that OpenAPI 3.1 builds on. Your issue and PR are what moved it up the queue, so: credit for the nudge.

I want to be upfront and specific about where this landed, because you put real work in and you deserve a real answer.

The parser itself is solid. The single-pass scan, the overflow handling (bounding before you multiply rather than catching the wrap after), the sign and fraction handling, the fixed-length calendar conversions — that's the careful part, and you did it carefully.

Where it needs more is the part that isn't the parser. strfmt is a foundational building block for the whole go-swagger ecosystem, and a "format" here is not just a validator — it's a type that has to travel losslessly across every serialization boundary (JSON, text, SQL driver.Valuer/Scanner, BSON, the mapstructure decode hook), register itself in the Registry.
Also pick up the conv pointer helpers... All of it consistent with the ~25 formats already there.
And the hard constraint on top: it has to do that without breaking the existing "duration" format, which today is the Go human-readable one (1h30m).

Reconciling "the standard says duration is the RFC 3339 one" with "existing users rely on duration meaning the Go one" turned out to drive a fair amount of design (explicit duration-human / duration-iso8601 handles, plus a separate JSON-Schema-2020 registry that resolves plain duration to the ISO type by context).

On top of that, the bar we hold ourselves to for a change like this includes the stuff that's invisible until it saves you: validating the strict grammar against the official JSON Schema Test Suite, a fuzz corpus, benchmarks against the standard library, and integration tests against real Postgres/MariaDB/Mongo.

Plus a strict-vs-lenient policy split, because the JSON Schema duration grammar is stricter than what's convenient to accept programmatically.

Because that added up to substantial surrounding design rather than line edits, piling change requests onto #280 didn't feel like the respectful move — you'd be chasing a moving target through code that's mostly plumbing. So I've prepared a companion PR (#284 ) that supersedes #280 while keeping the same goal and, honestly, the same core approach you took. I'd genuinely value your review on it, and I'll make sure you're credited for the origin and the direction.

Really — thanks for pushing on this. It's the kind of contribution that makes a library better even when the merge button ends up somewhere slightly different.