Timestamp Format (JSON messages)

Simscope uses timestamps encoded in RFC-3339 format for JSON messages.

• The RFC-3339 format is a stricter subset of ISO 8601
• This format includes a year, month, date, hour, minute, second, and timezone.

Format

The format for a RFC-3339 timestamp is:

yyyy-mm-ddThh:mm:ss-tz

• Note: to use UTC timezone, you can suffix the timestamp with Z instead of -XX:XX.

Example RFC-3339 timestamps

Here are example valid RFC-3339 timestamps, using different timezone formats:

Blank/empty timestamps in JSON

To signify a blank timestamp in JSON, there are 3 options:

1. Omit the entire timestamp line (key + value) from the JSON.

{
    // starttime omitted
}

2. (recommended) Set the value to null. For example:

{
    "starttime": null
}

3. Set the value to a zero timestamp:

{
    "starttime": "0001-01-01T00:00:00Z"
}

Note: blank strings are not allowed to signify a blank timestamp.

{
    // Blank string NOT allowed => use null instead
    "starttime": ""
}

→ To fix, use null instead.

How to generate RFC-3339 timestamps

Here are a few ways to generate complaint timestamps.

Python3 now()

If you want to get the current time (aka now) as an RFC-3339 string:

from datetime import datetime
local_time = datetime.now().astimezone()
print(local_time.isoformat())

Example output:

2021-09-05T11:29:14-05:00

Python3 Unix epoch integer timestamp

To convert from a Unix epoch integer timestamp to RFC-3339:

from datetime import datetime
epoch = 1631211917 # unix epoch integer timestamp
local_time = datetime.fromtimestamp(epoch).astimezone()
print(local_time.isoformat())

Example output:

2021-09-09T13:25:17-05:00

Ruby

To get the current timestamp from Ruby as an RFC-3339 string:

require 'date'
Time.now.to_datetime.rfc3339

Example output:

→ "2021-09-11T11:05:45-05:00"

Ruby Unix epoch integer timestamp

To convert from a Unix epoch integer timestamp to RFC-3339:

require 'date'
epoch = 1631211917 # unix epoch integer timestamp
Time.at(epoch).to_datetime.rfc3339

Example output:

→ "2020-03-01T22:11:20-06:00"

Linux shell (command-line)

(note this does not work on FreeBSD/Mac)

$ date '+%FT%T.%N%:z'
2020-02-28T00:27:08.914365057+00:00

FreeBSD shell (or MacOS)

(note this rounds to seconds, instead of nanoseconds)

$ date -u +%FT%TZ
2020-04-03T00:11:53Z

Unix Epoch

Here are a few helpers when working with Unix epoch timestamps.

Linux

Print the current Unix epoch timestamp (in seconds):

$ date +%s
1583180514

Convert from Unix epoch (in seconds) to RFC-3339:

# Replace EPOCH with an epoch timestamp
$ date --date=@EPOCH '+%FT%T.%N%:z'

# Example:
$ date --date=@1500000000 '+%FT%T.%N%:z'
2017-07-14T02:40:00.000000000+00:00

Mac/FreeBSD

Print the current Unix epoch timestamp (in seconds):

$ date +%s
1583180514

Convert from Unix epoch (in seconds) to RFC-3339:

# NOTE: replace EPOCH with an epoch timestamp
$ date -r EPOCH +%FT%T%Z

# Example:
$ date -r 1500000000 -u +%FT%TZ
2017-07-14T02:40:00Z

Source Control

There are examples of source control model timestamps (ie SHAs/checkins/changelists) here:

• Git commit timestamps
• Perforce changelist timestamps