Status: Work in progress 🚧
Specification for a custom GraphQL Scalar which represents an exact point in time. This point in time is specified by having an offset to UTC and does not use time zone.
All definitions of RFC 3339 are adopted and nothing is added or removed unless explicitly mentioned here.
The following refinements/clarifications apply:
This scalar represents a “date-time” as specified in section 5.6 of RFC 3339.
The other productions in section 5.6 are only used to support "date-time" but never stand alone for this Scalar.
RFC 3339 defines
time-secfrac optional as:
time-secfrac = "." 1*DIGIT (Meaning 1 or more DIGIT)
This allows for an unlimited numbers of digits. For this scalar the rule is not optional anymore and refined as:
time-secfrac = "." DIGIT DIGIT DIGIT
consisting always of exact three digits representing milliseconds.
Section 4.3 says:
If the time in UTC is known, but the offset to local time is unknown, this can be represented with an offset of "-00:00".
In order to simplify this Scalar this convention is dropped and an offset of
-00:00 is not allowed.
The accepted values are implementation specific, but it is recommend to accept Strings and other types representing Dates.
The outcome of the result Coercion should always be a String formatted as "date-time" as described above.
UTC offset should be formatted as
Z and not
+00:00 and lower case
t should be converted to
Only String literals are accepted formatted as "date-time" as described above.
The output value is implementation specific, but the value should accurately capture a "date-time" as described above. It is especially discouraged to use a value with a time zone instead of an offset, because time zone to offset conversion is non trivial.
The specific values for the input are implementation specific, but they should be semantically equivalent to "date-time" without any conversion. It is especially discouraged to accept values with time zones instead of offsets, because the conversion from time zone to offset is non trivial.
These are valid Strings accepted for the input of Literal Coercion:
|A DateTime with UTC offset (+00:00).|
|A DateTime with |
|A DateTime with -3h offset.|
|A DateTime with +3h 30min offset.|
These are invalid Strings which should be rejected as Literal Coercion Input and should not be an output of Result Coercion:
|String||Why is it invalid|
|The minutes of the offset are missing.|
|Too many digits for fractions of a second. Exactly three expected.|
|Fractions of a second are missing.|
|No offset provided.|
|No time provided.|
|Negative offset (|
|Seconds are not allowed for the offset|
|30th of February is not a valid date|
|25 is not a valid hour for offset|
The obvious recommended name for the Scalar is
If this name is not available then one alternative is
OffsetDateTime, which describes the Scalar quite accurately.