[docs] Documentation for DefaultJavaDurationReads doesn't match behavior

[tmccombs]

Play JSON Version (2.5.x / etc)

3.0.3

API (Scala / Java / Neither / Both)

Scala

Operating System (Ubuntu 15.10 / MacOS 10.10 / Windows 10)

Linux REDACTED 6.11.0-25-generic #25~24.04.1-Ubuntu SMP PREEMPT_DYNAMIC Tue Apr 15 17:20:50 UTC 2 x86_64 x86_64 x86_64 GNU/Linux

JDK (Oracle 1.8.0_72, OpenJDK 1.8.x, Azul Zing)

openjdk version "21.0.7" 2025-04-15 LTS
OpenJDK Runtime Environment Corretto-21.0.7.6.1 (build 21.0.7+6-LTS)
OpenJDK 64-Bit Server VM Corretto-21.0.7.6.1 (build 21.0.7+6-LTS, mixed mode, sharing)

Expected Behavior

Documentation of play.api.libs.json.Reads.DefaultJavaDurationReads consistent with behavior

Actual Behavior

Said documentation states:

Deserializer of Java Duration, from either a time-based amount of time (string representation such as '34.5 seconds')

However, the example of "34.5 seconds" isn't actually valid, and something like JsString("34.5 seconds").validate[java.time.Duration] return an "error.invalid.duration" JsError.

Looking at the source code, and the tests, it appears it actually uses ISO 8601 style duration format. So that should be "PT34.5S" instead of "34.5 seconds".

I'm not entirely sure if the intention was that a string like that SHOULD be accepted, or if the documentation should just be changed, but given that there is a test that asserts something similar should fail, I'm guessing the latter.