json-schema-spec
json-schema-spec copied to clipboard
json-schema-org
Should `"format": "duration"` allow fractional seconds?
Draft 2020-12 7.3.1. Dates, Times, and Duration states:
Date and time format names are derived from RFC 3339, section 5.6. The duration format is from the ISO 8601 ABNF as given in Appendix A of RFC 3339.
- ...
- duration: A string instance is valid against this attribute if it is a valid representation according to the "duration" ABNF rule (referenced above)
And the relevant section from RFC 3339:
Durations:
dur-second = 1*DIGIT "S"
dur-minute = 1*DIGIT "M" [dur-second]
dur-hour = 1*DIGIT "H" [dur-minute]
dur-time = "T" (dur-hour / dur-minute / dur-second)
dur-day = 1*DIGIT "D"
dur-week = 1*DIGIT "W"
dur-month = 1*DIGIT "M" [dur-day]
dur-year = 1*DIGIT "Y" [dur-month]
dur-date = (dur-day / dur-month / dur-year) [dur-time]
duration = "P" (dur-date / dur-time / dur-week)
Following this to the letter would mean that fractional seconds are not valid, e.g. "PT0.5S" (half a second) is not a valid duration. While there's no test in the JSON Schema test suite for this, the few validators that I tested do match this behaviour i.e. they disallow fractional seconds.
While this behaviour is not necessarily "incorrect", nor is it ambiguous, I'm concerned that it limits the utility and interoperability of the duration format, and is counter to consumer expectations. For example:
- Temporal.Duration (also based on ISO 8601) allows fractional seconds
- Jiff (itself heavily inspired by Temporal) SignedDuration and Span both allow fractional seconds
- XML Schema 1.1 duration (also based on ISO 8601) allows fractional seconds
- The original request for this format even included an example value with fraction seconds!
Now that I think about it, the same issue exists for negative durations, e.g. "-PT1S" (negative one second) is not a valid duration according to JSON Schema, despite being widely supported by various standards based on ISO 8601.
That's an interesting question, and I'm sure there could be use cases for it. Have you seen usages of RFC3339 duration with fractional seconds in a context where they're claiming to follow the RFC?
We typically follow a strict interpretation, so I'd imagine these would be disallowed. I'd be open to including an allowance in the next version, though.
Have you seen usages of RFC3339 duration with fractional seconds in a context where they're claiming to follow the RFC?
I haven't actually seen usages of RFC3339 duration at all.
That spec doesn't really make any attempt to define or standardize durations outside of appendix A, which is just an attempt at defining a formal grammar for ISO 8601. That appendix also states that it is "informational only and may contain errors" - in my opinion, the absence of negative/fractionals is exactly that, an error
That's good info. Thanks. It's probably the start of a strong case to start supporting ISO 8601 instead with the next spec version.
Note that full ISO 8601 includes a lot of representations that should probably not be available here, such as P0.5M (section 5.5.2.3: «The lowest order component may have a decimal fraction.»), and excludes some representations that might belong, such as P1M1W1D (section 5.5.2.2.: «The complete representation of the expression for duration shall be one of: a) [“P”][i][“Y”][i][“M”][i][“D”][“T”][i][“H”][i][“M”][i][“S”]; b) [“P”][i][“W”].»)—and also some that could go either way, such as PT1,00H (section 3.2.6: «the “.” period and “,” comma characters are decimal sign used to separate the integer part from the decimal fraction of a number»). Temporal is explicit about these: https://tc39.es/proposal-temporal/#sec-temporal-iso8601grammar
RFC 9557 and ISO 8601 are similar, but ISO 8601 defines a number of optional deviations that are allowed "by agreement between the communicating parties". The following is a list of deviations supported by this grammar:
- …
- Anything else described by ISO 8601 as requiring mutual agreement between communicating parties, is disallowed.
The main problem with using ISO specifications is that the full text of the spec is not free (as in money), so it's difficult to implement it correctly.
If you stick to the Temporal subset (linked above), then that sidesteps the "spec is not free" problem.
I (evidently erroneously) allow fractional seconds, but not any of the other fractionals. We don't have any tests that disallowed it and I have use cases where it is handy.
If we change the accepted ABNF for the duration format, it should be in the next version, and we need to be explicit about the changes -- e.g. instead of saying "we use the ABNF as it is in RFC3339 Appendix A", we would say "we use the commonly-accepted ABNF for ISO8601 durations, as defined at <link>". We can't be handwavey about sort of doing what the RFC says and sort of not, if we're not clear to both users and implementors what the differences are.
So, as it stands, the current suite of tests are correct, and it would also be valid to add tests to confirm that fractional units are not currently allowed.
That said, I'm in favour of allowing fractional units at any level, in the future.
As I am new, I would be interested about that particular topic, if there is a chance to be considered in the near future. I could just see that it is Open for discussion, not knowing what that means about the chance to get it considered. It would be a required to validate logfiles with time stamp & duration with fractions of seconds (at least ms or less).
@EasyWolf67 this is the spec repo. This here are reserved for members and other experts. Please d the contributing guide in the community repo for where you can help.