Proposals

About BEVE Extensions

BEVE supports extensions to handle specialized use cases while maintaining compatibility with the core specification. These proposals are working drafts that may be incorporated into future versions of BEVE.

Extension 4 — Time (Timestamps)

Working draft for BEVE v1.0

Overview

A compact, SIMD-friendly encoding for instants in time that:

• Round-trips cleanly to RFC 3339 / ISO-8601 (and IXDTF/RFC 9557) on the text side
• Avoids floating point (no drift)
• Scales to attoseconds without requiring 128-bit math for "now"
• Supports high-throughput typed arrays

Goals

• Exact representation of instants using integer ticks
• Two-integer split for precision and range without bigints on the hot path
• Single-value and array encodings with one set of metadata per array (epoch, unit, optional TZ)
• Straightforward JSON projections: human (strings) and lossless (object)

Placement in BEVE Header Space

This is a BEVE Extension (HEADER top 3 bits = 6).

Within the extension space, id = 4 denotes Time (timestamps).

All multi-byte integers in this extension are little endian.

TIME HEADER (1 byte)

bits 0..1  SHAPE
           0 = single timestamp
           1 = timestamp array (exactly length 2)
           2..3 = reserved

bits 2..4  UNIT (decimal powers around seconds)
           0 = ksec (10^3 s)
           1 = s
           2 = ms   (10^-3 s)
           3 = µs   (10^-6 s)
           4 = ns   (10^-9 s)
           5 = ps   (10^-12 s)
           6 = fs   (10^-15 s)
           7 = as   (10^-18 s)

bit 5      TZ_PRESENT
           0 = no TZ field follows
           1 = int16_t minutes east of UTC follows (fixed 2 bytes)

bits 6..7  EPOCH/SCALE
           0 = UNIX/POSIX (no leap seconds)
           1 = UTC scale  (permits leap seconds)
           2 = TAI
           3 = GPS

Timezone field (optional; fixed width)

If TZ_PRESENT=1, immediately write a 2-byte int16_t: minutes east of UTC.

• Valid range to emit: −1439..+1439 (encoders MUST enforce)
• Semantics: presentation metadata only; does not affect the instant encoded by the numeric fields

Payload Layouts

Single timestamp

EXT(4) | TIME_HEADER | [TZ:int16]? |
NUMBER (signed)   SECONDS_OFFSET |
NUMBER (unsigned) PRECISION

• NUMBER is a BEVE integer value (the usual number header chooses width: 1/2/4/8/16/32 bytes, etc.)

Timestamp array

EXT(4) | TIME_HEADER | [TZ:int16]? |
ARRAY(len=2) |
TYPED_ARRAY (signed int)   SECONDS_OFFSET[] |
TYPED_ARRAY (unsigned int) PRECISION[]

• The BEVE array header MUST report length = 2 (seconds array first, precision array second)
• Both typed arrays MUST have the same SIZE and are written back-to-back
• Each typed array uses standard BEVE typed-array headers

JSON/Text Projections

Human-oriented (default): RFC 3339 strings

• Single: "2025-10-16T12:34:56.123456789Z"
• Array: ["2025-10-16T12:34:56Z", "..."]
• Fractional digits match the UNIT (e.g., ns → up to 9 digits)
• If TZ_PRESENT=1, use that offset for printing (e.g., -05:00), while the instant remains absolute

Lossless structured object

Single:

{
  "epoch": "unix",                 // "unix" | "utc" | "tai" | "gps"
  "unit": "ps",                    // "ksec","s","ms","us","ns","ps","fs","as"
  "seconds": 1750000000,           // signed integer
  "precision": 123456789012,       // unsigned integer
  "offset_minutes": -300           // optional; omitted if TZ not present
}

Array:

{
  "epoch": "unix",
  "unit": "ns",
  "offset_minutes": 0,
  "seconds":   [1697463296, 1697466896],
  "precision": [        42,  987654321]
}

Examples

Single, UNIX epoch, nanoseconds, UTC

Meaning: 2025-10-16T12:34:56.000000789Z

EXT(4) | TH(shape=single, unit=ns, tz=0, epoch=unix) |
NUMBER(int64) seconds=1697463296 |
NUMBER(uint32) precision=789

Array, UNIX epoch, microseconds, TZ = −05:00

Meaning: local offset preserved for printing; instants absolute.

EXT(4) | TH(shape=array, unit=us, tz=1, epoch=unix) | int16(-300) |
TYPED_ARRAY(int64)   seconds[ N ] |
TYPED_ARRAY(uint32)  precision[ N ]

ksec example

• unit = ksec
• seconds = 2 (→ 2000 s), precision = 17 → instant = epoch + 2017 s

Key Features

Contributing to Proposals

We welcome feedback and contributions to BEVE proposals. To participate:

• Join the discussion on GitHub Discussions
• Submit issues or suggestions on the GitHub repository
• Review and comment on active proposals in the proposals directory