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

1. Default Timezone: When no timezone is specified in datetime values, UTC is assumed

2. Timezone Preservation: Explicit timezone information in datetime values is preserved during round-trip operations

3. Offset Interpretation: Timezone offsets are interpreted according to ISO 8601 standards

4. Range Validation: Timezone offsets must be within valid ranges (-12:00 to +14:00)

5. Format Support: Both ±HH:mm and ±HHMM offset formats are supported during parsing

6. 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)

See Also

• String Values Overview

• Base64 Byte String

• Raw String

• Regular String