ISO 8601 vs RFC 3339: dua format tanggal di balik tanggapan API Anda

Bidang 'ISO 8601' yang menolak ISO 8601 yang valid — tanggal seminggu atau nilai presisi rendah yang dikirim ke API yang mengharapkan RFC 3339

Bidang API yang dideskripsikan dengan santai sebagai “ISO 8601” hanya dapat menerima satu bentuk tanggal-waktu. Mengirimkan representasi lain yang memenuhi standar masih dapat menggagalkan parsernya. Solusinya adalah jangan berdebat dari nama umum; itu untuk mendokumentasikan tata bahasa kawat yang tepat dengan contoh dan tes validasi.

ToolAcre menyumbangkan keluaran kanonik yang stabil dari `Date.toISOString()`, namun ini bukan jaringan kesesuaian untuk setiap representasi. Perlakukan string yang dihasilkan sebagai salah satu bentuk pertukaran yang berguna dan bandingkan dengan kontrak API yang sebenarnya Anda miliki.

Oleh karena itu, skema harus menerbitkan ekspresi reguler atau tipe formal hanya jika skema tersebut mencerminkan parser secara akurat. Contoh-contoh saja sudah berguna, namun penolakan yang eksplisit menimbulkan ambiguitas.

Standar tanggal yang luas dan tata bahasa API yang sempit tidak dapat dipertukarkan

Formulir yang dihasilkan berisi tanggal kalender, `T`, waktu hingga milidetik dan di akhir Z. Implementasinya menyebutnya ISO 8601 (UTC) di UI. Input menerima apa yang dibaca oleh JavaScript Tanggal, termasuk offset eksplisit dan bentuk tanggal-waktu tanpa zona dari pemilih lokal.

Perilaku itu jauh lebih sempit daripada parser standar lengkap. Tanggal minggu, interval, durasi, dan pengurangan presisi tidak memiliki pengujian repositori. Dengan demikian, string yang diterima oleh satu browser Tanggal tidak dijamin di seluruh bahasa, dan formulir khusus yang ditolak tidak menyangkal kedudukannya di tempat lain.

Ketepatan milidetik keluaran yang tetap adalah pilihan pemformatan, bukan bukti bahwa sumber mengukur milidetik. Tanggal mungkin menerima nilai satu detik penuh dan masih mencetak `.000`.

ToolAcre mengeluarkan satu bentuk berbentuk ISO; itu tidak memvalidasi standar ISO 8601 penuh

Buku kerja ini menjelaskan RFC 3339, tahunnya dan aturan offset wajibnya. Tidak ada teks RFC atau parser khusus di kumpulan sumber, jadi rincian tersebut tidak ditegaskan. Kontrak penulisan memerlukan penghilangan presisi yang tidak didukung daripada mengutip judul dari ingatan.

Jika API Anda berarti RFC 3339, beri nama dalam skema dan uji terhadap implementasi yang didasarkan pada spesifikasi sebenarnya. ToolAcre dapat menjembatani periode yang diketahui ke keluaran UTC ISO untuk perbandingan, namun tidak dapat menyatakan bahwa masukan arbitrer memenuhi profil tersebut.

Ini adalah perlindungan editorial dan rekayasa: profil standar adalah kontrak yang tepat, dan memparafrasekannya tanpa teks berisiko mengubah persyaratan dalam dokumentasi.

Persyaratan RFC 3339 memerlukan sumber standar eksternal yang tidak ada dalam repositori ini

Klaim tentang pemisah alternatif, penanda huruf kecil, dan `−00:00` bergantung pada bahasa standar yang tepat. Mereka dihilangkan di sini. Detektor zona milik konverter mengenali akhiran Z atau angka `±HH:MM` dan menandai tanggal-waktu tanpa zona sebagai lokal; itulah batas yang dapat kami verifikasi.

Bangun validasi API dari contoh yang diterima secara eksplisit dan kasus penolakan. Jangan menyimpulkan izin dari pengurai kenyamanan JavaScript Tanggal. Browser yang permisif dapat menormalkan input yang ditolak dengan benar oleh server yang ketat, menyembunyikan cacat interoperabilitas selama pengujian manual.

Parser khusus yang sadar standar harus mengembalikan alasan kesalahan terstruktur. Membiarkan Date menormalkan input luas dapat mengubah bug validasi API menjadi perbedaan lintas platform di kemudian hari.

Pemisah spesifik dan aturan offset yang tidak diketahui dihilangkan tanpa teks standar

Nilai zaman membuat aritmatika dan pengurutan menjadi kompak ketika satuan dan titik asal ditetapkan. Tanggal-waktu tekstual membuat UTC atau pembacaan offset terlihat oleh orang-orang dan mempertahankan penanda tersebut dalam perjalanan. Banyak API memilih satu string kanonik untuk menghindari ambiguitas JavaScript bilangan bulat atau unit.

Jika API membawa keduanya, tentukan bidang mana yang otoritatif dan uji kesepakatan. String berformat basi di samping zaman baru lebih buruk daripada hanya satu string saja. ToolAcre dapat membandingkan pasangan dengan mengonversi bilangan bulat dan memeriksa nilai ISO yang dihasilkan, tetapi penegakan konsistensi berada di tangan produsen.

Contoh praktis: satu instan, empat representasi — epoch detik, epoch milidetik, string RFC 3339 dalam UTC dan satu dengan offset lokal

Gunakan `2025-02-03T10:22:00.000Z` instan. Bentuk zamannya adalah 1,738,578,120 detik dan 1,738,578,120,000 milidetik. Pembacaan offset eksplisit adalah `2025-02-03T12:22:00+02:00`; menguraikannya di ToolAcre akan mengembalikan epoch dan baris kanonik UTC ISO yang sama.

Ini adalah empat representasi yang dapat diverifikasi repositori: detik, milidetik, keluaran toISOString, dan string offset numerik yang diurai tanggal. Contoh ini tidak mengklaim bahwa setiap parser eksternal menerima presisi pecahan atau sintaks offset yang sama. Jalankan validasi API sendiri sebelum pengiriman.

Mengurangi offset +02:00 dari jam tertulis akan menghasilkan 10:22 UTC. Persamaan sederhana tersebut sudah cukup untuk menguji masukan khusus ini tanpa menggeneralisasi tata bahasa standar secara lengkap.

Contoh praktis: satu instan dalam empat bentuk yang dapat diverifikasi oleh repositori ini

HTTP header dan tanggal email menggunakan kontrak tekstual yang tidak diterapkan di sini. ToolAcre tidak memformat protokol tersebut, juga tidak menjanjikan bahwa keluaran ISO-nya dapat diganti. Instan stempel waktu bisa sama, namun representasi kabel yang diperlukan berbeda.

Simpan serialisasi protokol di adaptor khusus dengan perlengkapan yang disalin dari spesifikasi resmi. Gunakan konversi zaman untuk memverifikasi instan yang mendasarinya, lalu uji tata bahasa secara terpisah. Hal ini mencegah nilai yang benar kalender melewati tinjauan dalam amplop yang tidak valid secara sintaksis.

Adaptor khusus juga harus menjaga apakah offset yang hilang atau tidak diketahui membawa arti domain. Meratakan setiap tanggal tekstual menjadi asumsi lokal dapat menghancurkan informasi tersebut.

Protokol tekstual lainnya tetap berada di luar konverter

Tentukan format sempit yang diterima API Anda alih-alih mengandalkan label luas. Untuk alat ini, keluaran teraman yang dapat direproduksi adalah string UTC ISO yang dikembalikan oleh `toISOString()`, dan masukan numerik teraman mencakup kontrak detik atau milidetik yang eksplisit.

ToolAcre menjembatani asumsi formulir dan laporan tersebut. Ia tidak mengadili semua kasus tepi ISO 8601 atau RFC 3339. Kepemilikan yang jelas atas tata bahasa, satuan, dan penanda zona menjadikan stempel waktu mudah dibawa-bawa—tidak melampirkan nama standar yang familiar ke bidang yang kurang ditentukan.

Kontrak yang tepat memungkinkan klien gagal lebih awal dengan pesan-pesan yang bermanfaat. Label yang luas mendorong ketidaksepakatan ke dalam runtime, di mana dua parser yang benar dapat memilih subset yang berbeda.