diff --git a/docs/standard/datetime/system-text-json-support.md b/docs/standard/datetime/system-text-json-support.md index 9e67e8df0973c..7da9a7c5c42a2 100644 --- a/docs/standard/datetime/system-text-json-support.md +++ b/docs/standard/datetime/system-text-json-support.md @@ -186,6 +186,12 @@ The following levels of granularity are defined for parsing: 3. "yyyy'-'MM'-'dd'T'HH':'mm':'ss('+'/'-')HH':'mm" 4. "yyyy'-'MM'-'dd'T'HH':'mm':'ss'.'FFFFFFF('+'/'-')HH':'mm" + This level of granularity is compliant with [RFC 3339](https://tools.ietf.org/html/rfc3339#section-5.6), a widely adopted profile of ISO 8601 used for interchanging date and time information. However, there are a few restrictions in the System.Text.Json implementation. + + - RFC 3339 does not specify a maximum number of fractional-second digits, but specifies that at least one digit must follow the period, if a fractional-second section is present. The implementation in System.Text.Json allows up to 16 digits (to support interop with other programming languages and frameworks), but parses only the first seven. A will be thrown if there are more than 16 fractional second digits when reading `DateTime` and `DateTimeOffset` instances. + - RFC 3339 allows the "T" and "Z" characters to be "t" or "z" respectively, but allows applications to limit support to just the upper-case variants. The implementation in System.Text.Json requires them to be "T" and "Z". A will be thrown if input payloads contain "t" or "z" when reading `DateTime` and `DateTimeOffset` instances. + - RFC 3339 specifies that the date and time sections are separated by "T", but allows applications to separate them by a space (" ") instead. System.Text.Json requires date and time sections to be separated with "T". A will be thrown if input payloads contain a space (" ") when reading `DateTime` and `DateTimeOffset` instances. + If there are decimal fractions for seconds, there must be at least one digit; `2019-07-26T00:00:00.` is not allowed. While up to 16 fractional digits are allowed, only the first seven are parsed. Anything beyond that is considered a zero. For example, `2019-07-26T00:00:00.1234567890` will be parsed as if it is `2019-07-26T00:00:00.1234567`. @@ -224,6 +230,8 @@ The following levels of granularity are defined for formatting: Used to format a or with fractional seconds and with a local offset. + This level of granularity is compliant with [RFC 3339](https://tools.ietf.org/html/rfc3339#section-5.6). + If the [round-trip format](../base-types/standard-date-and-time-format-strings.md#the-round-trip-o-o-format-specifier) representation of a or instance has trailing zeros in its fractional seconds, then and will format a representation of the instance without trailing zeros.