Date Time Processing

Date/Time Processing

Article Type: How-To Audience: Developers, App Admins Module: How To

JSONata provides a set of functions for capturing, formatting, and parsing date/time values. Because JSON has no native date/time type, these values are conventionally stored and exchanged as ISO 8601 strings.

The 'evaluation time' — $now()

There are two functions that return the 'current' date/time timestamp:

1. $now() returns the timestamp in an ISO 8601 formatted string.
2. $millis() returns the same timestamp as the number of milliseconds since midnight on 1 January 1970 UTC (the Unix epoch).

The timestamp is captured at the start of the expression evaluation, and that same timestamp value is returned for every occurrence of $now() and $millis() in the same expression for the duration of the evaluation.

Example — the timestamp will be the same for all invocations within an expression:

{
  "invoiceTime": $now(),
  "total": $sum(Account.Order.Product.(Price * Quantity)),
  "closingTime": $now()
}

{
  "invoiceTime": "2018-12-10T13:49:51.141Z",
  "total": 336.36,
  "closingTime": "2018-12-10T13:49:51.141Z"
}

JSON and ISO 8601

JSON does not have a built-in type for date/time values. The general consensus is to store the date/time value as a string in ISO 8601 format.

Example

{
  "myDateTime": "2018-12-10T13:45:00.000Z"
}

JSONata follows this convention and provides functions for formatting and parsing ISO 8601 formatted timestamps ($toMillis() and $fromMillis()).

Support for Other Date/Time Formats

Since there is no standard for date/time format in JSON, it is entirely possible that the JSON data you are working with will have date/time values formatted in other ways. JSONata supports the highly versatile picture string notation from the XPath/XQuery fn:format-dateTime() specification for both the formatting and parsing of a wide variety of date/time formats. See $toMillis() and $fromMillis() for details.

Examples

The date 12/10/2018 in US format and 10/12/2018 in European format both refer to the same day:

$toMillis('10/12/2018', '[D]/[M]/[Y]') ~> $fromMillis('[M]/[D]/[Y]')

"12/10/2018"

A more verbose format:

$toMillis('10/12/2018', '[D]/[M]/[Y]')
  ~> $fromMillis('[FNn], [D1o] [MNn] [YI]')

"Monday, 10th December MMXVIII"

See Also

• Date-Time-Functions
• Jsonata-Tutorial
• Expressions
• Composition

---

Source: support.fuuz.com