Date and Time

Date and time values in Internet Object

Date and Time values in Internet Object are represented using annotated strings that follow ISO 8601-compatible formats. These provide built-in support for temporal data with automatic parsing to native Date objects during deserialization. Internet Object supports three distinct temporal types: dates, times, and combined date-time values.

Date and time values are scalar values that represent temporal data. The content between the quotes must be valid according to their respective format specifications.

Syntax

dateTimeValue = dateValue | timeValue | dateTimeValue
dateValue     = "d" (singleQuotedDate | doubleQuotedDate)
timeValue     = "t" (singleQuotedTime | doubleQuotedTime)
dateTimeValue = "dt" (singleQuotedDateTime | doubleQuotedDateTime)

singleQuotedDate = "'" dateContent "'"
doubleQuotedDate = '"' dateContent '"'
Date and time values use specific annotation prefixes followed by quoted content:

```ebnf
dateTimeValue = dateValue | timeValue | dateTimeValue
dateValue = "d" (singleQuotedDate | doubleQuotedDate)
timeValue = "t" (singleQuotedTime | doubleQuotedTime)
dateTimeValue = "dt" (singleQuotedDateTime | doubleQuotedDateTime)

singleQuotedDate = "'" dateContent "'"
doubleQuotedDate = '"' dateContent '"'
singleQuotedTime = "'" timeContent "'"
doubleQuotedTime = '"' timeContent '"'
singleQuotedDateTime = "'" dateTimeContent "'"
doubleQuotedDateTime = '"' dateTimeContent '"'

dateContent = yearPart [monthPart [dayPart]]
timeContent = hourPart [minutePart [secondPart [millisecondPart]]]
dateTimeContent = yearPart [monthPart [dayPart]] ["T" hourPart [minutePart [secondPart [millisecondPart]]]] [timeZone]

yearPart = digit4
monthPart = ["-"] (("0" digit1-9) | ("1" ("0" | "1" | "2")))
dayPart = ["-"] (("0" digit1-9) | (("1" | "2") digit0-9) | ("3" ("0" | "1")))
hourPart = [":"] (("0" | "1") digit0-9) | ("2" ("0" | "1" | "2" | "3"))
minutePart = [":"] (("0" | "1" | "2" | "3" | "4" | "5") digit0-9)
secondPart = [":"] (("0" | "1" | "2" | "3" | "4" | "5") digit0-9)
millisecondPart = "." digit3+
timeZone = "Z" | (("+" | "-") hourPart [minutePart])

Structural Characters

The following characters are used to structure date and time values:

Symbol

Name

Unicode

Description

d

Date Prefix

U+0064

Indicates date-only value

t

Time Prefix

U+0074

Indicates time-only value

dt

DateTime Prefix

Indicates combined date-time value

'

Single Quote

U+0027

Encloses temporal content

"

Double Quote

U+0022

Encloses temporal content

-

Hyphen

U+002D

Date separator (optional)

:

Colon

U+003A

Time separator (optional)

.

Period

U+002E

Millisecond separator

T

Letter T

U+0054

Date-time separator

Z

Letter Z

U+005A

UTC timezone designator

+

Plus Sign

U+002B

Positive timezone offset

-

Minus Sign

U+002D

Negative timezone offset

0-9

Digits

U+0030-U+0039

Numeric components

Valid Forms

Date Values (`d'...'`)

Examples of valid date values:

d'2024-03-20'                          # Full date with separators
d'2024-03'                             # Year and month (day defaults to 01)
d'2024'                                # Year only (month and day default to 01)
d'20240320'                            # Full date without separators
d'202403'                              # Year and month without separators
d"2024-12-31"                          # Double quotes supported

Time Values (`t'...'`)

Examples of valid time values:

t'14:30:45.123'                        # Full time with milliseconds
t'14:30:45'                            # Hour, minute, second
t'14:30'                               # Hour and minute (second defaults to 00)
t'14'                                  # Hour only (minute and second default to 00)
t'143045123'                           # Without separators
t'143045'                              # Without separators, no milliseconds
t'1430'                                # Without separators, hour and minute
t"09:00:00"                            # Double quotes supported

DateTime Values (`dt'...'`)

Examples of valid datetime values:

dt'2024-03-20T14:30:45.123Z'           # Full datetime with timezone
dt'2024-03-20T14:30:45.123'            # Full datetime, no timezone
dt'2024-03-20T14:30:45'                # Without milliseconds
dt'2024-03-20T14:30'                   # Without seconds
dt'2024-03-20T14'                      # Without minutes
dt'2024-03-20'                         # Date only (time defaults to 00:00:00.000)
dt'20240320T143045123Z'                # Without separators
dt'2024-03-20T14:30:45+05:30'          # With timezone offset
dt'2024-03-20T14:30:45-08:00'          # Negative timezone offset
dt"2024-12-31T23:59:59.999Z"           # Double quotes supported

Format Specifications

Date Format

With separators: YYYY-MM-DD
Without separators: YYYYMMDD
Partial formats: YYYY-MM, YYYY, YYYYMM
Defaults: Missing month defaults to 01, missing day defaults to 01

Time Format

With separators: HH:mm:ss.SSS
Without separators: HHmmss.SSS
Partial formats: HH:mm:ss, HH:mm, HH
Defaults: Missing components default to 00
24-hour format: Hours range from 00 to 23

DateTime Format

Combined: Date + T + Time + optional timezone
Timezone: Z (UTC) or ±HH:mm or ±HHMM
Partial: Any valid date format + optional time components
Defaults: Missing time defaults to 00:00:00.000, missing timezone defaults to Z

Optional Behaviors

Whitespace: Leading and trailing whitespace around quotes are ignored
Separators: Both separated (2024-03-20) and non-separated (20240320) formats are supported
Partial Values: Missing components are filled with appropriate defaults
Timezone: If no timezone is specified, UTC (Z) is assumed for datetime values
Validation: Parser validates format compliance and logical date/time values
Quote Style: Both single and double quotes are supported

Invalid Forms

Examples of invalid date and time values:

d2024-03-20                            # ✗ Missing quotes
d'2024-13-20'                          # ✗ Invalid month (13)
d'2024-02-30'                          # ✗ Invalid date for February
t'25:00:00'                            # ✗ Invalid hour (25)
t'12:60:00'                            # ✗ Invalid minute (60)
dt'2024-03-20 14:30:00'                # ✗ Missing T separator
dt'2024-03-20T14:30:00+25:00'          # ✗ Invalid timezone offset
d'2024-03-20T14:30:00'                 # ✗ Date prefix with time component
t'2024-03-20T14:30:00'                 # ✗ Time prefix with date component
dt'2024-03-20T14:30:00.123456'         # ✗ More than 3 millisecond digits

Parsing Behavior

When processed by an Internet Object parser:

Date values (d'...') are parsed to Date objects with time set to 00:00:00.000Z
Time values (t'...') are parsed to Date objects with date set to 1900-01-01
DateTime values (dt'...') are parsed to complete Date objects
Missing components are filled with appropriate defaults
Invalid formats result in parsing errors
The parsed Date object maintains the exact temporal representation

Preservation of Structure

Internet Object preserves:

The exact format as written (with or without separators)
The choice of single or double quotes
The specific annotation prefix (d, t, or dt)
The timezone information for datetime values

It does not interpret or enforce:

Calendar-specific constraints beyond basic validity
Leap year calculations during parsing (handled by Date constructor)
Business logic constraints (e.g., working hours, holidays)

Type Conversion

During parsing:

All temporal values are converted to native date/time objects in the target platform
Date-only values have time components set to midnight UTC
Time-only values have date components set to a reference date (typically 1900-01-01)
Timezone information is preserved in the resulting date object
Missing timezone defaults to UTC for datetime values

Timezone Handling

Deserialization (Parsing)

When parsing date-time values from Internet Object format:

DateTime Values (dt'...'):

Explicit UTC (Z): dt'2024-03-20T14:30:45.123Z' → Represents UTC time
Explicit Offset: dt'2024-03-20T14:30:45.123+05:30' → Represents time with specific timezone offset, Indian Standard Time (IST) in this case
No Timezone: dt'2024-03-20T14:30:45.123' → Treated as UTC (default behavior)

Date Values (d'...'):

Always treated as UTC at midnight: d'2024-03-20' → 2024-03-20T00:00:00.000Z
No timezone information is preserved or needed for date-only values

Time Values (t'...'):

No timezone information is applicable for time-only values, will always be treated as UTC.

Serialization (Stringification)

When converting native date/time objects back to Internet Object format:

Date Objects to DateTime (dt'...'):

UTC dates: Serialized with Z suffix → dt'2024-03-20T14:30:45.123Z'
Dates with timezone info: Serialized with appropriate offset → dt'2024-03-20T14:30:45.123+05:30'
Local dates: Should be converted to UTC and serialized with Z suffix

Date Objects to Date (d'...'):

Time components are omitted, timezone is not included → d'2024-03-20'
Always represents the date portion regardless of original timezone

Date Objects to Time (t'...'):

Date components are omitted, timezone is not included → t'14:30:45.123'
Represents the time portion regardless of original timezone

Timezone Behavior Rules

Default Timezone: When no timezone is specified in datetime values, UTC is assumed
Timezone Preservation: Explicit timezone information in datetime values is preserved during round-trip operations
Offset Interpretation: Timezone offsets are interpreted according to ISO 8601 standards
Range Validation: Timezone offsets must be within valid ranges (-12:00 to +14:00)
Format Support: Both ±HH:mm and ±HHMM offset formats are supported during parsing
Serialization Consistency: Serialization should use the ±HH:mm format for timezone offsets

Examples

Parsing Examples:

dt'2024-03-20T14:30:45Z'           # → UTC time: 2024-03-20T14:30:45.000Z
dt'2024-03-20T14:30:45+05:30'      # → UTC equivalent: 2024-03-20T09:00:45.000Z
dt'2024-03-20T14:30:45-08:00'      # → UTC equivalent: 2024-03-20T22:30:45.000Z
dt'2024-03-20T14:30:45'            # → UTC time: 2024-03-20T14:30:45.000Z (default)
d'2024-03-20'                      # → Date: 2024-03-20 (time irrelevant)
t'14:30:45'                        # → Time: 14:30:45.000 (date irrelevant)

Serialization Examples:

# UTC time: 2024-03-20T14:30:45.000Z
→ dt'2024-03-20T14:30:45.000Z'     # DateTime format
→ d'2024-03-20'                    # Date format
→ t'14:30:45'                      # Time format

# Time with offset: 2024-03-20T14:30:45.000+05:30
→ dt'2024-03-20T14:30:45.000+05:30' # DateTime format with offset
→ d'2024-03-20'                     # Date format (timezone ignored)
→ t'14:30:45'                       # Time format (timezone ignored)