[{"data":1,"prerenderedAt":684},["ShallowReactive",2],{"guide-iso-8601-format-guide":3},{"id":4,"title":5,"body":6,"date":61,"description":677,"extension":678,"meta":679,"navigation":438,"path":680,"readingTime":448,"seo":681,"stem":682,"__hash__":683},"guides\u002Fguides\u002Fiso-8601-format-guide.md","ISO 8601 Date Format Guide",{"type":7,"value":8,"toc":658},"minimark",[9,18,23,26,31,120,127,131,200,215,219,226,236,239,243,246,269,275,279,285,289,296,342,355,359,363,374,493,499,503,517,521,524,528,608,612,641,645,654],[10,11,12,13,17],"p",{},"ISO 8601 is the international standard for representing dates and times in a machine-readable, unambiguous format. If you have worked with REST APIs, database schemas, or log files, you have already encountered it — strings like ",[14,15,16],"code",{},"2026-05-28T14:30:00Z"," are ISO 8601 timestamps. This guide covers the format's structure, common patterns, and the pitfalls developers hit most often.",[19,20,22],"h2",{"id":21},"basic-format-structure","Basic Format Structure",[10,24,25],{},"ISO 8601 prescriptions follow a most-significant-to-least-significant order — year, month, day, hour, minute, second — which makes chronological and lexicographic sorting identical.",[27,28,30],"h3",{"id":29},"date","Date",[32,33,34,50],"table",{},[35,36,37],"thead",{},[38,39,40,44,47],"tr",{},[41,42,43],"th",{},"Format",[41,45,46],{},"Example",[41,48,49],{},"Description",[51,52,53,65,76,87,98,109],"tbody",{},[38,54,55,59,62],{},[56,57,58],"td",{},"YYYY-MM-DD",[56,60,61],{},"2026-05-28",[56,63,64],{},"Calendar date",[38,66,67,70,73],{},[56,68,69],{},"YYYY-MM",[56,71,72],{},"2026-05",[56,74,75],{},"Year and month",[38,77,78,81,84],{},[56,79,80],{},"YYYY",[56,82,83],{},"2026",[56,85,86],{},"Year only",[38,88,89,92,95],{},[56,90,91],{},"YYYY-DDD",[56,93,94],{},"2026-148",[56,96,97],{},"Ordinal date (148th day of 2026)",[38,99,100,103,106],{},[56,101,102],{},"YYYY-Www",[56,104,105],{},"2026-W22",[56,107,108],{},"Week date (22nd week of 2026)",[38,110,111,114,117],{},[56,112,113],{},"YYYY-Www-D",[56,115,116],{},"2026-W22-4",[56,118,119],{},"Week date with day (Thursday of week 22)",[10,121,122,123,126],{},"The hyphens are mandatory in the extended format (shown above). A compact format without hyphens — ",[14,124,125],{},"20260528"," — is also valid but less readable.",[27,128,130],{"id":129},"time","Time",[32,132,133,143],{},[35,134,135],{},[38,136,137,139,141],{},[41,138,43],{},[41,140,46],{},[41,142,49],{},[51,144,145,156,167,178,189],{},[38,146,147,150,153],{},[56,148,149],{},"hh:mm:ss",[56,151,152],{},"14:30:00",[56,154,155],{},"Local time",[38,157,158,161,164],{},[56,159,160],{},"hh:mm:ssZ",[56,162,163],{},"14:30:00Z",[56,165,166],{},"UTC (Zulu) time",[38,168,169,172,175],{},[56,170,171],{},"hh:mm:ss+05:30",[56,173,174],{},"14:30:00+05:30",[56,176,177],{},"UTC offset +5:30",[38,179,180,183,186],{},[56,181,182],{},"hh:mm",[56,184,185],{},"14:30",[56,187,188],{},"Hours and minutes only",[38,190,191,194,197],{},[56,192,193],{},"hhmmss",[56,195,196],{},"143000",[56,198,199],{},"Compact format",[10,201,202,203,206,207,210,211,214],{},"The ",[14,204,205],{},"Z"," suffix stands for \"Zulu time\" (UTC+0). Any other offset is written as ",[14,208,209],{},"±hh:mm"," (or ",[14,212,213],{},"±hhmm"," in compact form).",[27,216,218],{"id":217},"combined-date-and-time","Combined Date and Time",[10,220,221,222,225],{},"The date and time are joined by the letter ",[14,223,224],{},"T",":",[227,228,233],"pre",{"className":229,"code":231,"language":232},[230],"language-text","2026-05-28T14:30:00Z\n2026-05-28T14:30:00+02:00\n2026-05-28T14:30:00.123Z       (with milliseconds)\n2026-05-28T14:30:00.123456Z    (with microseconds)\n","text",[14,234,231],{"__ignoreMap":235},"",[10,237,238],{},"The fractional seconds can have any number of decimal places, though most implementations standardize on 3 (milliseconds) or 6 (microseconds).",[19,240,242],{"id":241},"timezone-handling","Timezone Handling",[10,244,245],{},"The most common source of confusion in ISO 8601 is timezone interpretation:",[247,248,249,257,263],"ul",{},[250,251,252,256],"li",{},[253,254,255],"strong",{},"Z suffix:"," The timestamp is in UTC. No conversion needed.",[250,258,259,262],{},[253,260,261],{},"Offset present:"," The timestamp is in the specified offset. Convert to UTC by subtracting the offset.",[250,264,265,268],{},[253,266,267],{},"No offset or Z:"," The timestamp is \"local\" time with no timezone information. This is ambiguous — local to whom?",[10,270,271,272,274],{},"Avoid offsetless timestamps in APIs and databases. Always include ",[14,273,205],{}," or an explicit offset.",[27,276,278],{"id":277},"timezone-conversion-example","Timezone conversion example",[227,280,283],{"className":281,"code":282,"language":232},[230],"2026-05-28T14:30:00+02:00  (Berlin, summer)\n→ Subtract offset: 14:30 - 02:00 = 12:30\n→ UTC equivalent: 2026-05-28T12:30:00Z\n",[14,284,282],{"__ignoreMap":235},[19,286,288],{"id":287},"duration-format","Duration Format",[10,290,291,292,295],{},"ISO 8601 also defines a duration format using the ",[14,293,294],{},"P"," prefix:",[32,297,298,308],{},[35,299,300],{},[38,301,302,305],{},[41,303,304],{},"Duration",[41,306,307],{},"Meaning",[51,309,310,318,326,334],{},[38,311,312,315],{},[56,313,314],{},"P1Y2M3D",[56,316,317],{},"1 year, 2 months, 3 days",[38,319,320,323],{},[56,321,322],{},"PT12H30M",[56,324,325],{},"12 hours, 30 minutes",[38,327,328,331],{},[56,329,330],{},"P1Y2M3DT12H30M15S",[56,332,333],{},"Combined date and time duration",[38,335,336,339],{},[56,337,338],{},"P1W",[56,340,341],{},"1 week",[10,343,202,344,346,347,350,351,354],{},[14,345,224],{}," separates date components from time components. Note that ",[14,348,349],{},"P1M"," is one month (not one minute), while ",[14,352,353],{},"PT1M"," is one minute.",[19,356,358],{"id":357},"common-pitfalls","Common Pitfalls",[27,360,362],{"id":361},"parsing-inconsistencies","Parsing inconsistencies",[10,364,365,366,369,370,373],{},"Not all ISO 8601 parsers handle all variations. JavaScript's ",[14,367,368],{},"Date.parse()"," and ",[14,371,372],{},"new Date()"," accept many formats but behave inconsistently across engines:",[227,375,379],{"className":376,"code":377,"language":378,"meta":235,"style":235},"language-javascript shiki shiki-themes github-light github-dark","\u002F\u002F These work in most engines:\nnew Date('2026-05-28T14:30:00Z')       \u002F\u002F OK — UTC\nnew Date('2026-05-28T14:30:00+02:00')  \u002F\u002F OK — with offset\n\n\u002F\u002F This is treated as LOCAL time in some engines, UTC in others:\nnew Date('2026-05-28T14:30:00')        \u002F\u002F Dangerous — no offset\n\n\u002F\u002F Date-only strings are treated as UTC:\nnew Date('2026-05-28')                 \u002F\u002F Midnight UTC, not local\n","javascript",[14,380,381,390,415,433,440,446,464,469,475],{"__ignoreMap":235},[382,383,386],"span",{"class":384,"line":385},"line",1,[382,387,389],{"class":388},"sJ8bj","\u002F\u002F These work in most engines:\n",[382,391,393,397,401,405,409,412],{"class":384,"line":392},2,[382,394,396],{"class":395},"szBVR","new",[382,398,400],{"class":399},"sScJk"," Date",[382,402,404],{"class":403},"sVt8B","(",[382,406,408],{"class":407},"sZZnC","'2026-05-28T14:30:00Z'",[382,410,411],{"class":403},")       ",[382,413,414],{"class":388},"\u002F\u002F OK — UTC\n",[382,416,418,420,422,424,427,430],{"class":384,"line":417},3,[382,419,396],{"class":395},[382,421,400],{"class":399},[382,423,404],{"class":403},[382,425,426],{"class":407},"'2026-05-28T14:30:00+02:00'",[382,428,429],{"class":403},")  ",[382,431,432],{"class":388},"\u002F\u002F OK — with offset\n",[382,434,436],{"class":384,"line":435},4,[382,437,439],{"emptyLinePlaceholder":438},true,"\n",[382,441,443],{"class":384,"line":442},5,[382,444,445],{"class":388},"\u002F\u002F This is treated as LOCAL time in some engines, UTC in others:\n",[382,447,449,451,453,455,458,461],{"class":384,"line":448},6,[382,450,396],{"class":395},[382,452,400],{"class":399},[382,454,404],{"class":403},[382,456,457],{"class":407},"'2026-05-28T14:30:00'",[382,459,460],{"class":403},")        ",[382,462,463],{"class":388},"\u002F\u002F Dangerous — no offset\n",[382,465,467],{"class":384,"line":466},7,[382,468,439],{"emptyLinePlaceholder":438},[382,470,472],{"class":384,"line":471},8,[382,473,474],{"class":388},"\u002F\u002F Date-only strings are treated as UTC:\n",[382,476,478,480,482,484,487,490],{"class":384,"line":477},9,[382,479,396],{"class":395},[382,481,400],{"class":399},[382,483,404],{"class":403},[382,485,486],{"class":407},"'2026-05-28'",[382,488,489],{"class":403},")                 ",[382,491,492],{"class":388},"\u002F\u002F Midnight UTC, not local\n",[10,494,495,496,498],{},"The safest approach: always serialize with ",[14,497,205],{}," or an explicit offset, and always use a dedicated date library (date-fns, Luxon, Day.js) for parsing.",[27,500,502],{"id":501},"leap-seconds","Leap seconds",[10,504,505,506,509,510,513,514,516],{},"ISO 8601 allows the second value ",[14,507,508],{},"60"," to represent a positive leap second: ",[14,511,512],{},"23:59:60Z",". Most Unix systems smooth leap seconds across the day rather than exposing them, so timestamps with ",[14,515,508],{}," seconds are rarely generated but should be handled gracefully by parsers.",[27,518,520],{"id":519},"week-date-edge-cases","Week date edge cases",[10,522,523],{},"Week dates follow ISO week numbering, where weeks start on Monday and the first week of the year contains the first Thursday. This means December 29 may belong to the first week of the next year, and January 1–3 may belong to the last week of the previous year.",[19,525,527],{"id":526},"iso-8601-in-practice","ISO 8601 in Practice",[32,529,530,542],{},[35,531,532],{},[38,533,534,537,540],{},[41,535,536],{},"Context",[41,538,539],{},"Recommended Format",[41,541,46],{},[51,543,544,556,569,582,595],{},[38,545,546,549,552],{},[56,547,548],{},"REST API responses",[56,550,551],{},"ISO 8601 with Z",[56,553,554],{},[14,555,16],{},[38,557,558,561,564],{},[56,559,560],{},"Database columns (PostgreSQL)",[56,562,563],{},"TIMESTAMPTZ stores UTC",[56,565,566],{},[14,567,568],{},"2026-05-28 14:30:00+00",[38,570,571,574,577],{},[56,572,573],{},"Log files",[56,575,576],{},"ISO 8601 with milliseconds",[56,578,579],{},[14,580,581],{},"2026-05-28T14:30:00.123Z",[38,583,584,587,590],{},[56,585,586],{},"File naming",[56,588,589],{},"Compact, no colons",[56,591,592],{},[14,593,594],{},"20260528T143000Z",[38,596,597,600,603],{},[56,598,599],{},"HTTP headers (If-Modified-Since)",[56,601,602],{},"IMF fixdate (RFC 7231)",[56,604,605],{},[14,606,607],{},"Thu, 28 May 2026 14:30:00 GMT",[19,609,611],{"id":610},"key-takeaways","Key Takeaways",[247,613,614,617,623,632,638],{},[250,615,616],{},"ISO 8601 orders components from most to least significant, making string sort match chronological sort.",[250,618,619,620,622],{},"Always include a timezone indicator (",[14,621,205],{}," or offset) — offsetless timestamps are ambiguous.",[250,624,625,626,628,629,631],{},"Use ",[14,627,294],{}," for durations and ",[14,630,224],{}," to separate date from time components within a duration.",[250,633,634,635,637],{},"Avoid relying on JavaScript's native ",[14,636,30],{}," parser for ISO 8601; use a dedicated library.",[250,639,640],{},"Compact formats without delimiters are valid but reduce readability.",[19,642,644],{"id":643},"try-it-yourself","Try It Yourself",[10,646,647,648,653],{},"Need to convert between ISO 8601 formats and Unix timestamps? The ",[649,650,652],"a",{"href":651},"\u002Ftools\u002Ftimestamp-converter","Timestamp Converter"," handles both directions with support for UTC offsets and fractional seconds.",[655,656,657],"style",{},"html pre.shiki code .sJ8bj, html code.shiki .sJ8bj{--shiki-default:#6A737D;--shiki-dark:#6A737D}html pre.shiki code .szBVR, html code.shiki .szBVR{--shiki-default:#D73A49;--shiki-dark:#F97583}html pre.shiki code .sScJk, html code.shiki .sScJk{--shiki-default:#6F42C1;--shiki-dark:#B392F0}html pre.shiki code .sVt8B, html code.shiki .sVt8B{--shiki-default:#24292E;--shiki-dark:#E1E4E8}html pre.shiki code .sZZnC, html code.shiki .sZZnC{--shiki-default:#032F62;--shiki-dark:#9ECBFF}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}",{"title":235,"searchDepth":392,"depth":392,"links":659},[660,665,668,669,674,675,676],{"id":21,"depth":392,"text":22,"children":661},[662,663,664],{"id":29,"depth":417,"text":30},{"id":129,"depth":417,"text":130},{"id":217,"depth":417,"text":218},{"id":241,"depth":392,"text":242,"children":666},[667],{"id":277,"depth":417,"text":278},{"id":287,"depth":392,"text":288},{"id":357,"depth":392,"text":358,"children":670},[671,672,673],{"id":361,"depth":417,"text":362},{"id":501,"depth":417,"text":502},{"id":519,"depth":417,"text":520},{"id":526,"depth":392,"text":527},{"id":610,"depth":392,"text":611},{"id":643,"depth":392,"text":644},"Complete reference for the international date-time format used in APIs and databases.","md",{"immutable":438},"\u002Fguides\u002Fiso-8601-format-guide",{"title":5,"description":677},"guides\u002Fiso-8601-format-guide","Iu6xNyDbhFxrn6uAD-EodTf2ZO-tlDvI5J8qA-BSJPg",1780401334669]