Format Tanggal di JSON: ISO 8601, Unix Timestamp, dan Timezone

Oleh Andi Putra Ogie · Update: Juli 2026 · 8 menit baca

Bug terkait tanggal adalah salah satu sumber masalah paling sering di aplikasi yang berkomunikasi lewat JSON — mulai dari tanggal yang "mundur satu hari" karena timezone, sampai error parsing karena format tanggal berbeda antara backend dan frontend. Masalahnya berakar dari satu fakta sederhana: JSON tidak punya tipe data date bawaan. Spesifikasi JSON cuma mengenal string, number, boolean, null, object, array — titik. Semua representasi tanggal di JSON sebenarnya cuma string atau number biasa yang "disepakati" formatnya oleh aplikasi.

Kenapa JSON Tidak Punya Tipe Date?

JSON dirancang sederhana dan minimal secara sengaja oleh Douglas Crockford. Menambahkan tipe date akan membuka masalah baru: format apa yang dipakai? Timezone gimana? Kalender apa (Gregorian saja, atau harus mendukung kalender lain)? Daripada membuka kotak pandora ini, JSON membiarkan aplikasi memilih representasi sendiri, biasanya lewat string dengan format yang disepakati. Keputusan desain minimalis ini sebenarnya konsisten dengan filosofi JSON secara keseluruhan — spesifikasinya sengaja dibuat sekecil mungkin supaya mudah diimplementasikan ulang di hampir semua bahasa pemrograman tanpa ambiguitas.

Opsi 1: ISO 8601 (Paling Direkomendasikan)

ISO 8601 adalah standar internasional untuk representasi tanggal dan waktu, dan menjadi konvensi de facto paling umum dipakai di JSON API modern:

{
  "createdAt": "2026-07-15T09:30:00Z",
  "birthDate": "1997-03-22"
}

Beberapa komponen penting dalam format ini:

• 2026-07-15 — tanggal, format YYYY-MM-DD, tidak ambigu karena selalu tahun-bulan-tanggal (beda dengan format regional seperti DD/MM/YYYY vs MM/DD/YYYY yang membingungkan).
• T — pemisah antara bagian tanggal dan waktu.
• 09:30:00 — waktu, format HH:MM:SS, 24 jam.
• Z — menandakan UTC (Zulu time). Kalau bukan UTC, offset ditulis eksplisit seperti +07:00 untuk WIB.

{
  "eventTime": "2026-07-15T16:30:00+07:00"
}

Kelebihan: universal, bisa langsung di-parse oleh hampir semua bahasa pemrograman modern (new Date() di JavaScript, datetime.fromisoformat() di Python), human-readable, dan urutan alfabetis string-nya sama dengan urutan kronologis (berguna untuk sorting sederhana tanpa parsing).

Opsi 2: Unix Timestamp

Unix timestamp merepresentasikan waktu sebagai jumlah detik (atau milidetik) sejak 1 Januari 1970 00:00:00 UTC:

{
  "createdAt": 1784094600
}

Kelebihan: ringkas (number, bukan string panjang), tidak ambigu soal timezone karena selalu relatif ke UTC, mudah dipakai untuk kalkulasi matematis (selisih waktu tinggal dikurangi).
Kekurangan: tidak human-readable sama sekali — kamu tidak bisa langsung tahu ini tanggal berapa hanya dengan melihat angkanya, harus dikonversi dulu. Juga rawan ambiguitas detik vs milidetik — beberapa sistem (seperti JavaScript Date.now()) pakai milidetik, sementara yang lain (seperti Unix time standar) pakai detik, dan salah asumsi bisa bikin tanggal meleset ribuan tahun.

// JavaScript pakai milidetik
Date.now()  // 1784094600000

// Python time.time() pakai detik (float)
time.time()  // 1784094600.123

Opsi 3: Format Kustom (Sebaiknya Dihindari)

Beberapa sistem lama masih memakai format kustom seperti "15/07/2026" atau "July 15, 2026". Ini sebaiknya dihindari di API baru karena ambigu (DD/MM vs MM/DD) dan sulit di-parse otomatis tanpa tahu locale/format spesifiknya terlebih dahulu. Kalau kamu terpaksa bekerja dengan sistem yang memakai format ini, selalu dokumentasikan formatnya secara eksplisit dan jangan biarkan client menebak.

Masalah Timezone yang Sering Muncul

Salah satu bug paling umum: menyimpan/mengirim tanggal tanpa informasi timezone, sehingga ambigu jam berapa sebenarnya di lokasi berbeda:

// Ambigu — timezone mana?
{ "meetingTime": "2026-07-15T14:00:00" }

// Jelas — eksplisit UTC
{ "meetingTime": "2026-07-15T14:00:00Z" }

// Jelas — eksplisit offset WIB
{ "meetingTime": "2026-07-15T21:00:00+07:00" }

Praktik terbaik: selalu simpan dan kirim waktu dalam UTC di backend/API, lalu konversi ke timezone lokal user hanya di sisi presentasi/UI. Ini menghindari bug klasik seperti "meeting muncul di jam yang salah" ketika user dan server berada di timezone berbeda.

Tanggal Tanpa Waktu (Date-Only)

Untuk data yang memang cuma butuh tanggal tanpa jam spesifik (misalnya tanggal lahir), gunakan format tanggal saja tanpa komponen waktu:

{ "birthDate": "1997-03-22" }

Hindari menambahkan waktu palsu seperti "1997-03-22T00:00:00Z" untuk data yang secara konsep tidak punya waktu, karena ini bisa menimbulkan bug timezone — tanggal lahir yang disimpan sebagai midnight UTC bisa "mundur satu hari" kalau ditampilkan di timezone yang lebih lambat dari UTC.

Durasi dan Interval

Untuk merepresentasikan durasi (bukan titik waktu), ISO 8601 juga punya format khusus:

{ "sessionTimeout": "PT30M" }

PT30M berarti "period time 30 minutes". Format ini kurang umum dipakai dibanding representasi durasi dalam angka detik/menit biasa ("sessionTimeoutSeconds": 1800), tapi berguna kalau kamu butuh presisi kalender seperti "P1M" (1 bulan, yang panjangnya bisa bervariasi 28-31 hari). Untuk kebanyakan API internal yang tidak butuh presisi kalender kompleks, representasi angka biasa dalam detik atau milidetik jauh lebih mudah dipahami dan dikalkulasi ulang di sisi client dibanding parsing string durasi ISO 8601 yang formatnya kurang familiar bagi banyak developer.

Konsistensi Antar Bahasa Pemrograman

Salah satu keuntungan ISO 8601 adalah dukungan native di hampir semua bahasa modern, tapi cara parsing-nya tetap perlu diperhatikan detailnya. JavaScript new Date("2026-07-15T09:30:00Z") bekerja langsung tanpa library tambahan. Python butuh datetime.fromisoformat() (Python 3.11+ sudah mendukung suffix Z secara native, versi lebih lama perlu .replace("Z", "+00:00") dulu). Java punya Instant.parse() dari paket java.time. Meskipun formatnya sama, selalu test parsing di bahasa dan versi runtime spesifik yang kamu pakai, karena ada perbedaan detail dukungan edge case antar versi. Perbedaan ini sering jadi sumber bug tersembunyi ketika tim backend dan mobile memakai bahasa berbeda dan salah satunya ternyata lebih strict soal format yang diterima.

Rekomendasi Praktis

• Untuk API baru, pakai ISO 8601 dengan timezone eksplisit (UTC/Z paling disarankan) sebagai default.
• Kalau butuh presisi tinggi untuk kalkulasi/perbandingan performa, Unix timestamp milidetik bisa jadi pilihan tambahan, tapi dokumentasikan satuannya dengan jelas (detik vs milidetik).
• Selalu konsisten satu format di seluruh API — jangan campur ISO 8601 di satu endpoint dan Unix timestamp di endpoint lain tanpa alasan kuat.
• Dokumentasikan format tanggal secara eksplisit di dokumentasi API (OpenAPI schema), termasuk apakah timezone selalu UTC atau bisa bervariasi.

🔧 Rapikan Contoh JSON dengan Field Tanggal di JSONYAMify

{
  "createdAt": "2026-07-15T09:30:00Z",
  "birthDate": "1997-03-22"
}

{
  "eventTime": "2026-07-15T16:30:00+07:00"
}

{
  "createdAt": 1784094600
}

// JavaScript uses milliseconds
Date.now()  // 1784094600000

// Python's time.time() uses seconds (float)
time.time()  // 1784094600.123

// Ambiguous — which timezone?
{ "meetingTime": "2026-07-15T14:00:00" }

// Clear — explicit UTC
{ "meetingTime": "2026-07-15T14:00:00Z" }

// Clear — explicit offset for Jakarta
{ "meetingTime": "2026-07-15T21:00:00+07:00" }

{ "birthDate": "1997-03-22" }

{ "sessionTimeout": "PT30M" }