forked from excitement-engineer/graphql-iso-date
-
Notifications
You must be signed in to change notification settings - Fork 0
/
rfc3339.txt
1011 lines (628 loc) · 34.2 KB
/
rfc3339.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
Network Working Group G. Klyne
Request for Comments: 3339 Clearswift Corporation
Category: Standards Track C. Newman
Sun Microsystems
July 2002
Date and Time on the Internet: Timestamps
Status of this Memo
This document specifies an Internet standards track protocol for the
Internet community, and requests discussion and suggestions for
improvements. Please refer to the current edition of the "Internet
Official Protocol Standards" (STD 1) for the standardization state
and status of this protocol. Distribution of this memo is unlimited.
Copyright Notice
Copyright (C) The Internet Society (2002). All Rights Reserved.
Abstract
This document defines a date and time format for use in Internet
protocols that is a profile of the ISO 8601 standard for
representation of dates and times using the Gregorian calendar.
Table of Contents
1. Introduction ............................................ 2
2. Definitions ............................................. 3
3. Two Digit Years ......................................... 4
4. Local Time .............................................. 4
4.1. Coordinated Universal Time (UTC) ...................... 4
4.2. Local Offsets ......................................... 5
4.3. Unknown Local Offset Convention ....................... 5
4.4. Unqualified Local Time ................................ 5
5. Date and Time format .................................... 6
5.1. Ordering .............................................. 6
5.2. Human Readability ..................................... 6
5.3. Rarely Used Options ................................... 7
5.4. Redundant Information ................................. 7
5.5. Simplicity ............................................ 7
5.6. Internet Date/Time Format ............................. 8
5.7. Restrictions .......................................... 9
5.8. Examples ............................................. 10
6. References ............................................. 10
7. Security Considerations ................................ 11
Klyne, et. al. Standards Track [Page 1]
RFC 3339 Date and Time on the Internet: Timestamps July 2002
Appendix A. ISO 8601 Collected ABNF ....................... 12
Appendix B. Day of the Week ............................... 14
Appendix C. Leap Years .................................... 14
Appendix D. Leap Seconds ..............................,... 15
Acknowledgements .......................................... 17
Authors' Addresses ........................................ 17
Full Copyright Statement .................................. 18
1. Introduction
Date and time formats cause a lot of confusion and interoperability
problems on the Internet. This document addresses many of the
problems encountered and makes recommendations to improve consistency
and interoperability when representing and using date and time in
Internet protocols.
This document includes an Internet profile of the ISO 8601 [ISO8601]
standard for representation of dates and times using the Gregorian
calendar.
There are many ways in which date and time values might appear in
Internet protocols: this document focuses on just one common usage,
viz. timestamps for Internet protocol events. This limited
consideration has the following consequences:
o All dates and times are assumed to be in the "current era",
somewhere between 0000AD and 9999AD.
o All times expressed have a stated relationship (offset) to
Coordinated Universal Time (UTC). (This is distinct from some
usage in scheduling applications where a local time and location
may be known, but the actual relationship to UTC may be dependent
on the unknown or unknowable actions of politicians or
administrators. The UTC time corresponding to 17:00 on 23rd March
2005 in New York may depend on administrative decisions about
daylight savings time. This specification steers well clear of
such considerations.)
o Timestamps can express times that occurred before the introduction
of UTC. Such timestamps are expressed relative to universal time,
using the best available practice at the stated time.
o Date and time expressions indicate an instant in time.
Description of time periods, or intervals, is not covered here.
Klyne, et. al. Standards Track [Page 2]
RFC 3339 Date and Time on the Internet: Timestamps July 2002
2. Definitions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in RFC 2119 [RFC2119].
UTC Coordinated Universal Time as maintained by the Bureau
International des Poids et Mesures (BIPM).
second A basic unit of measurement of time in the
International System of Units. It is defined as the
duration of 9,192,631,770 cycles of microwave light
absorbed or emitted by the hyperfine transition of
cesium-133 atoms in their ground state undisturbed by
external fields.
minute A period of time of 60 seconds. However, see also the
restrictions in section 5.7 and Appendix D for how
leap seconds are denoted within minutes.
hour A period of time of 60 minutes.
day A period of time of 24 hours.
leap year In the Gregorian calendar, a year which has 366 days.
A leap year is a year whose number is divisible by
four an integral number of times, except that if it is
a centennial year (i.e. divisible by one hundred) it
shall also be divisible by four hundred an integral
number of times.
ABNF Augmented Backus-Naur Form, a format used to represent
permissible strings in a protocol or language, as
defined in [ABNF].
Email Date/Time Format
The date/time format used by Internet Mail as defined
by RFC 2822 [IMAIL-UPDATE].
Internet Date/Time Format
The date format defined in section 5 of this document.
Timestamp This term is used in this document to refer to an
unambiguous representation of some instant in time.
Z A suffix which, when applied to a time, denotes a UTC
offset of 00:00; often spoken "Zulu" from the ICAO
phonetic alphabet representation of the letter "Z".
Klyne, et. al. Standards Track [Page 3]
RFC 3339 Date and Time on the Internet: Timestamps July 2002
For more information about time scales, see Appendix E of [NTP],
Section 3 of [ISO8601], and the appropriate ITU documents [ITU-R-
TF].
3. Two Digit Years
The following requirements are to address the problems of ambiguity
of 2-digit years:
o Internet Protocols MUST generate four digit years in dates.
o The use of 2-digit years is deprecated. If a 2-digit year is
received, it should be accepted ONLY if an incorrect
interpretation will not cause a protocol or processing failure
(e.g. if used only for logging or tracing purposes).
o It is possible that a program using two digit years will
represent years after 1999 as three digits. This occurs if the
program simply subtracts 1900 from the year and doesn't check
the number of digits. Programs wishing to robustly deal with
dates generated by such broken software may add 1900 to three
digit years.
o It is possible that a program using two digit years will
represent years after 1999 as ":0", ":1", ... ":9", ";0", ...
This occurs if the program simply subtracts 1900 from the year
and adds the decade to the US-ASCII character zero. Programs
wishing to robustly deal with dates generated by such broken
software should detect non-numeric decades and interpret
appropriately.
The problems with two digit years amply demonstrate why all dates and
times used in Internet protocols MUST be fully qualified.
4. Local Time
4.1. Coordinated Universal Time (UTC)
Because the daylight saving rules for local time zones are so
convoluted and can change based on local law at unpredictable times,
true interoperability is best achieved by using Coordinated Universal
Time (UTC). This specification does not cater to local time zone
rules.
Klyne, et. al. Standards Track [Page 4]
RFC 3339 Date and Time on the Internet: Timestamps July 2002
4.2. Local Offsets
The offset between local time and UTC is often useful information.
For example, in electronic mail (RFC2822, [IMAIL-UPDATE]) the local
offset provides a useful heuristic to determine the probability of a
prompt response. Attempts to label local offsets with alphabetic
strings have resulted in poor interoperability in the past [IMAIL],
[HOST-REQ]. As a result, RFC2822 [IMAIL-UPDATE] has made numeric
offsets mandatory.
Numeric offsets are calculated as "local time minus UTC". So the
equivalent time in UTC can be determined by subtracting the offset
from the local time. For example, 18:50:00-04:00 is the same time as
22:50:00Z. (This example shows negative offsets handled by adding
the absolute value of the offset.)
NOTE: Following ISO 8601, numeric offsets represent only time
zones that differ from UTC by an integral number of minutes.
However, many historical time zones differ from UTC by a non-
integral number of minutes. To represent such historical time
stamps exactly, applications must convert them to a representable
time zone.
4.3. Unknown Local Offset Convention
If the time in UTC is known, but the offset to local time is unknown,
this can be represented with an offset of "-00:00". This differs
semantically from an offset of "Z" or "+00:00", which imply that UTC
is the preferred reference point for the specified time. RFC2822
[IMAIL-UPDATE] describes a similar convention for email.
4.4. Unqualified Local Time
A number of devices currently connected to the Internet run their
internal clocks in local time and are unaware of UTC. While the
Internet does have a tradition of accepting reality when creating
specifications, this should not be done at the expense of
interoperability. Since interpretation of an unqualified local time
zone will fail in approximately 23/24 of the globe, the
interoperability problems of unqualified local time are deemed
unacceptable for the Internet. Systems that are configured with a
local time, are unaware of the corresponding UTC offset, and depend
on time synchronization with other Internet systems, MUST use a
mechanism that ensures correct synchronization with UTC. Some
suitable mechanisms are:
o Use Network Time Protocol [NTP] to obtain the time in UTC.
Klyne, et. al. Standards Track [Page 5]
RFC 3339 Date and Time on the Internet: Timestamps July 2002
o Use another host in the same local time zone as a gateway to the
Internet. This host MUST correct unqualified local times that are
transmitted to other hosts.
o Prompt the user for the local time zone and daylight saving rule
settings.
5. Date and Time format
This section discusses desirable qualities of date and time formats
and defines a profile of ISO 8601 for use in Internet protocols.
5.1. Ordering
If date and time components are ordered from least precise to most
precise, then a useful property is achieved. Assuming that the time
zones of the dates and times are the same (e.g., all in UTC),
expressed using the same string (e.g., all "Z" or all "+00:00"), and
all times have the same number of fractional second digits, then the
date and time strings may be sorted as strings (e.g., using the
strcmp() function in C) and a time-ordered sequence will result. The
presence of optional punctuation would violate this characteristic.
5.2. Human Readability
Human readability has proved to be a valuable feature of Internet
protocols. Human readable protocols greatly reduce the costs of
debugging since telnet often suffices as a test client and network
analyzers need not be modified with knowledge of the protocol. On
the other hand, human readability sometimes results in
interoperability problems. For example, the date format "10/11/1996"
is completely unsuitable for global interchange because it is
interpreted differently in different countries. In addition, the
date format in [IMAIL] has resulted in interoperability problems when
people assumed any text string was permitted and translated the three
letter abbreviations to other languages or substituted date formats
which were easier to generate (e.g. the format used by the C function
ctime). For this reason, a balance must be struck between human
readability and interoperability.
Because no date and time format is readable according to the
conventions of all countries, Internet clients SHOULD be prepared to
transform dates into a display format suitable for the locality.
This may include translating UTC to local time.
Klyne, et. al. Standards Track [Page 6]
RFC 3339 Date and Time on the Internet: Timestamps July 2002
5.3. Rarely Used Options
A format which includes rarely used options is likely to cause
interoperability problems. This is because rarely used options are
less likely to be used in alpha or beta testing, so bugs in parsing
are less likely to be discovered. Rarely used options should be made
mandatory or omitted for the sake of interoperability whenever
possible.
The format defined below includes only one rarely used option:
fractions of a second. It is expected that this will be used only by
applications which require strict ordering of date/time stamps or
which have an unusual precision requirement.
5.4. Redundant Information
If a date/time format includes redundant information, that introduces
the possibility that the redundant information will not correlate.
For example, including the day of the week in a date/time format
introduces the possibility that the day of week is incorrect but the
date is correct, or vice versa. Since it is not difficult to compute
the day of week from a date (see Appendix B), the day of week should
not be included in a date/time format.
5.5. Simplicity
The complete set of date and time formats specified in ISO 8601
[ISO8601] is quite complex in an attempt to provide multiple
representations and partial representations. Appendix A contains an
attempt to translate the complete syntax of ISO 8601 into ABNF.
Internet protocols have somewhat different requirements and
simplicity has proved to be an important characteristic. In
addition, Internet protocols usually need complete specification of
data in order to achieve true interoperability. Therefore, the
complete grammar for ISO 8601 is deemed too complex for most Internet
protocols.
The following section defines a profile of ISO 8601 for use on the
Internet. It is a conformant subset of the ISO 8601 extended format.
Simplicity is achieved by making most fields and punctuation
mandatory.
Klyne, et. al. Standards Track [Page 7]
RFC 3339 Date and Time on the Internet: Timestamps July 2002
5.6. Internet Date/Time Format
The following profile of ISO 8601 [ISO8601] dates SHOULD be used in
new protocols on the Internet. This is specified using the syntax
description notation defined in [ABNF].
date-fullyear = 4DIGIT
date-month = 2DIGIT ; 01-12
date-mday = 2DIGIT ; 01-28, 01-29, 01-30, 01-31 based on
; month/year
time-hour = 2DIGIT ; 00-23
time-minute = 2DIGIT ; 00-59
time-second = 2DIGIT ; 00-58, 00-59, 00-60 based on leap second
; rules
time-secfrac = "." 1*DIGIT
time-numoffset = ("+" / "-") time-hour ":" time-minute
time-offset = "Z" / time-numoffset
partial-time = time-hour ":" time-minute ":" time-second
[time-secfrac]
full-date = date-fullyear "-" date-month "-" date-mday
full-time = partial-time time-offset
date-time = full-date "T" full-time
NOTE: Per [ABNF] and ISO8601, the "T" and "Z" characters in this
syntax may alternatively be lower case "t" or "z" respectively.
This date/time format may be used in some environments or contexts
that distinguish between the upper- and lower-case letters 'A'-'Z'
and 'a'-'z' (e.g. XML). Specifications that use this format in
such environments MAY further limit the date/time syntax so that
the letters 'T' and 'Z' used in the date/time syntax must always
be upper case. Applications that generate this format SHOULD use
upper case letters.
NOTE: ISO 8601 defines date and time separated by "T".
Applications using this syntax may choose, for the sake of
readability, to specify a full-date and full-time separated by
(say) a space character.
Klyne, et. al. Standards Track [Page 8]
RFC 3339 Date and Time on the Internet: Timestamps July 2002
5.7. Restrictions
The grammar element date-mday represents the day number within the
current month. The maximum value varies based on the month and year
as follows:
Month Number Month/Year Maximum value of date-mday
------------ ---------- --------------------------
01 January 31
02 February, normal 28
02 February, leap year 29
03 March 31
04 April 30
05 May 31
06 June 30
07 July 31
08 August 31
09 September 30
10 October 31
11 November 30
12 December 31
Appendix C contains sample C code to determine if a year is a leap
year.
The grammar element time-second may have the value "60" at the end of
months in which a leap second occurs -- to date: June (XXXX-06-
30T23:59:60Z) or December (XXXX-12-31T23:59:60Z); see Appendix D for
a table of leap seconds. It is also possible for a leap second to be
subtracted, at which times the maximum value of time-second is "58".
At all other times the maximum value of time-second is "59".
Further, in time zones other than "Z", the leap second point is
shifted by the zone offset (so it happens at the same instant around
the globe).
Leap seconds cannot be predicted far into the future. The
International Earth Rotation Service publishes bulletins [IERS] that
announce leap seconds with a few weeks' warning. Applications should
not generate timestamps involving inserted leap seconds until after
the leap seconds are announced.
Although ISO 8601 permits the hour to be "24", this profile of ISO
8601 only allows values between "00" and "23" for the hour in order
to reduce confusion.
Klyne, et. al. Standards Track [Page 9]
RFC 3339 Date and Time on the Internet: Timestamps July 2002
5.8. Examples
Here are some examples of Internet date/time format.
1985-04-12T23:20:50.52Z
This represents 20 minutes and 50.52 seconds after the 23rd hour of
April 12th, 1985 in UTC.
1996-12-19T16:39:57-08:00
This represents 39 minutes and 57 seconds after the 16th hour of
December 19th, 1996 with an offset of -08:00 from UTC (Pacific
Standard Time). Note that this is equivalent to 1996-12-20T00:39:57Z
in UTC.
1990-12-31T23:59:60Z
This represents the leap second inserted at the end of 1990.
1990-12-31T15:59:60-08:00
This represents the same leap second in Pacific Standard Time, 8
hours behind UTC.
1937-01-01T12:00:27.87+00:20
This represents the same instant of time as noon, January 1, 1937,
Netherlands time. Standard time in the Netherlands was exactly 19
minutes and 32.13 seconds ahead of UTC by law from 1909-05-01 through
1937-06-30. This time zone cannot be represented exactly using the
HH:MM format, and this timestamp uses the closest representable UTC
offset.
6. References
[ZELLER] Zeller, C., "Kalender-Formeln", Acta Mathematica, Vol.
9, Nov 1886.
[IMAIL] Crocker, D., "Standard for the Format of Arpa Internet
Text Messages", STD 11, RFC 822, August 1982.
[IMAIL-UPDATE] Resnick, P., "Internet Message Format", RFC 2822,
April 2001.
[ABNF] Crocker, D. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", RFC 2234, November 1997.
Klyne, et. al. Standards Track [Page 10]
RFC 3339 Date and Time on the Internet: Timestamps July 2002
[ISO8601] "Data elements and interchange formats -- Information
interchange -- Representation of dates and times", ISO
8601:1988(E), International Organization for
Standardization, June, 1988.
[ISO8601:2000] "Data elements and interchange formats -- Information
interchange -- Representation of dates and times", ISO
8601:2000, International Organization for
Standardization, December, 2000.
[HOST-REQ] Braden, R., "Requirements for Internet Hosts --
Application and Support", STD 3, RFC 1123, October
1989.
[IERS] International Earth Rotation Service Bulletins,
<http://hpiers.obspm.fr/eop-
pc/products/bulletins.html>.
[NTP] Mills, D, "Network Time Protocol (Version 3)
Specification, Implementation and Analysis", RFC 1305,
March 1992.
[ITU-R-TF] International Telecommunication Union Recommendations
for Time Signals and Frequency Standards Emissions.
<http://www.itu.ch/publications/itu-r/iturtf.htm>
[RFC2119] Bradner, S, "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
7. Security Considerations
Since the local time zone of a site may be useful for determining a
time when systems are less likely to be monitored and might be more
susceptible to a security probe, some sites may wish to emit times in
UTC only. Others might consider this to be loss of useful
functionality at the hands of paranoia.
Klyne, et. al. Standards Track [Page 11]
RFC 3339 Date and Time on the Internet: Timestamps July 2002
Appendix A. ISO 8601 Collected ABNF
This information is based on the 1988 version of ISO 8601. There may
be some changes in the 2000 revision.
ISO 8601 does not specify a formal grammar for the date and time
formats it defines. The following is an attempt to create a formal
grammar from ISO 8601. This is informational only and may contain
errors. ISO 8601 remains the authoritative reference.
Note that due to ambiguities in ISO 8601, some interpretations had to
be made. First, ISO 8601 is not clear if mixtures of basic and
extended format are permissible. This grammar permits mixtures. ISO
8601 is not clear on whether an hour of 24 is permissible only if
minutes and seconds are 0. This assumes that an hour of 24 is
permissible in any context. Restrictions on date-mday in section 5.7
apply. ISO 8601 states that the "T" may be omitted under some
circumstances. This grammar requires the "T" to avoid ambiguity.
ISO 8601 also requires (in section 5.3.1.3) that a decimal fraction
be proceeded by a "0" if less than unity. Annex B.2 of ISO 8601
gives examples where the decimal fractions are not preceded by a "0".
This grammar assumes section 5.3.1.3 is correct and that Annex B.2 is
in error.
date-century = 2DIGIT ; 00-99
date-decade = DIGIT ; 0-9
date-subdecade = DIGIT ; 0-9
date-year = date-decade date-subdecade
date-fullyear = date-century date-year
date-month = 2DIGIT ; 01-12
date-wday = DIGIT ; 1-7 ; 1 is Monday, 7 is Sunday
date-mday = 2DIGIT ; 01-28, 01-29, 01-30, 01-31 based on
; month/year
date-yday = 3DIGIT ; 001-365, 001-366 based on year
date-week = 2DIGIT ; 01-52, 01-53 based on year
datepart-fullyear = [date-century] date-year ["-"]
datepart-ptyear = "-" [date-subdecade ["-"]]
datepart-wkyear = datepart-ptyear / datepart-fullyear
dateopt-century = "-" / date-century
dateopt-fullyear = "-" / datepart-fullyear
dateopt-year = "-" / (date-year ["-"])
dateopt-month = "-" / (date-month ["-"])
dateopt-week = "-" / (date-week ["-"])
Klyne, et. al. Standards Track [Page 12]
RFC 3339 Date and Time on the Internet: Timestamps July 2002
datespec-full = datepart-fullyear date-month ["-"] date-mday
datespec-year = date-century / dateopt-century date-year
datespec-month = "-" dateopt-year date-month [["-"] date-mday]
datespec-mday = "--" dateopt-month date-mday
datespec-week = datepart-wkyear "W"
(date-week / dateopt-week date-wday)
datespec-wday = "---" date-wday
datespec-yday = dateopt-fullyear date-yday
date = datespec-full / datespec-year
/ datespec-month /
datespec-mday / datespec-week / datespec-wday / datespec-yday
Time:
time-hour = 2DIGIT ; 00-24
time-minute = 2DIGIT ; 00-59
time-second = 2DIGIT ; 00-58, 00-59, 00-60 based on
; leap-second rules
time-fraction = ("," / ".") 1*DIGIT
time-numoffset = ("+" / "-") time-hour [[":"] time-minute]
time-zone = "Z" / time-numoffset
timeopt-hour = "-" / (time-hour [":"])
timeopt-minute = "-" / (time-minute [":"])
timespec-hour = time-hour [[":"] time-minute [[":"] time-second]]
timespec-minute = timeopt-hour time-minute [[":"] time-second]
timespec-second = "-" timeopt-minute time-second
timespec-base = timespec-hour / timespec-minute / timespec-second
time = timespec-base [time-fraction] [time-zone]
iso-date-time = date "T" time
Durations:
dur-second = 1*DIGIT "S"
dur-minute = 1*DIGIT "M" [dur-second]
dur-hour = 1*DIGIT "H" [dur-minute]
dur-time = "T" (dur-hour / dur-minute / dur-second)
dur-day = 1*DIGIT "D"
dur-week = 1*DIGIT "W"
dur-month = 1*DIGIT "M" [dur-day]
dur-year = 1*DIGIT "Y" [dur-month]
dur-date = (dur-day / dur-month / dur-year) [dur-time]
duration = "P" (dur-date / dur-time / dur-week)
Klyne, et. al. Standards Track [Page 13]
RFC 3339 Date and Time on the Internet: Timestamps July 2002
Periods:
period-explicit = iso-date-time "/" iso-date-time
period-start = iso-date-time "/" duration
period-end = duration "/" iso-date-time
period = period-explicit / period-start / period-end
Appendix B. Day of the Week
The following is a sample C subroutine loosely based on Zeller's
Congruence [Zeller] which may be used to obtain the day of the week
for dates on or after 0000-03-01:
char *day_of_week(int day, int month, int year)
{
int cent;
char *dayofweek[] = {
"Sunday", "Monday", "Tuesday", "Wednesday",
"Thursday", "Friday", "Saturday"
};
/* adjust months so February is the last one */
month -= 2;
if (month < 1) {
month += 12;
--year;
}
/* split by century */
cent = year / 100;
year %= 100;
return (dayofweek[((26 * month - 2) / 10 + day + year
+ year / 4 + cent / 4 + 5 * cent) % 7]);
}
Appendix C. Leap Years
Here is a sample C subroutine to calculate if a year is a leap year:
/* This returns non-zero if year is a leap year. Must use 4 digit
year.
*/
int leap_year(int year)
{
return (year % 4 == 0 && (year % 100 != 0 || year % 400 == 0));
}
Klyne, et. al. Standards Track [Page 14]
RFC 3339 Date and Time on the Internet: Timestamps July 2002
Appendix D. Leap Seconds
Information about leap seconds can be found at:
<http://tycho.usno.navy.mil/leapsec.html>. In particular, it notes
that:
The decision to introduce a leap second in UTC is the
responsibility of the International Earth Rotation Service (IERS).
According to the CCIR Recommendation, first preference is given to
the opportunities at the end of December and June, and second
preference to those at the end of March and September.
When required, insertion of a leap second occurs as an extra second
at the end of a day in UTC, represented by a timestamp of the form
YYYY-MM-DDT23:59:60Z. A leap second occurs simultaneously in all
time zones, so that time zone relationships are not affected. See
section 5.8 for some examples of leap second times.
The following table is an excerpt from the table maintained by the
United States Naval Observatory. The source data is located at:
<ftp://maia.usno.navy.mil/ser7/tai-utc.dat>
Klyne, et. al. Standards Track [Page 15]
RFC 3339 Date and Time on the Internet: Timestamps July 2002
This table shows the date of the leap second, and the difference
between the time standard TAI (which isn't adjusted by leap seconds)
and UTC after that leap second.
UTC Date TAI - UTC After Leap Second
-------- ---------------------------
1972-06-30 11
1972-12-31 12
1973-12-31 13
1974-12-31 14
1975-12-31 15
1976-12-31 16
1977-12-31 17
1978-12-31 18
1979-12-31 19
1981-06-30 20
1982-06-30 21
1983-06-30 22
1985-06-30 23
1987-12-31 24
1989-12-31 25
1990-12-31 26
1992-06-30 27
1993-06-30 28
1994-06-30 29
1995-12-31 30
1997-06-30 31
1998-12-31 32
Klyne, et. al. Standards Track [Page 16]
RFC 3339 Date and Time on the Internet: Timestamps July 2002
Acknowledgements
The following people provided helpful advice for an earlier
incarnation of this document: Ned Freed, Neal McBurnett, David
Keegel, Markus Kuhn, Paul Eggert and Robert Elz. Thanks are also due
to participants of the IETF Calendaring/Scheduling working group
mailing list, and participants of the time zone mailing list.
The following reviewers contributed helpful suggestions for the
present revision: Tom Harsch, Markus Kuhn, Pete Resnick, Dan Kohn.
Paul Eggert provided many careful observations regarding the
subtleties of leap seconds and time zone offsets. The following
people noted corrections and improvements to earlier drafts: Dr John
Stockton, Jutta Degener, Joe Abley, and Dan Wing.
Authors' Addresses
Chris Newman
Sun Microsystems
1050 Lakes Drive, Suite 250
West Covina, CA 91790 USA
EMail: [email protected]
Graham Klyne (editor, this revision)
Clearswift Corporation
1310 Waterside
Arlington Business Park
Theale, Reading RG7 4SA
UK
Phone: +44 11 8903 8903
Fax: +44 11 8903 9000
EMail: [email protected]
Klyne, et. al. Standards Track [Page 17]
RFC 3339 Date and Time on the Internet: Timestamps July 2002
Full Copyright Statement
Copyright (C) The Internet Society (2002). All Rights Reserved.
This document and translations of it may be copied and furnished to
others, and derivative works that comment on or otherwise explain it
or assist in its implementation may be prepared, copied, published
and distributed, in whole or in part, without restriction of any
kind, provided that the above copyright notice and this paragraph are
included on all such copies and derivative works. However, this
document itself may not be modified in any way, such as by removing
the copyright notice or references to the Internet Society or other
Internet organizations, except as needed for the purpose of
developing Internet standards in which case the procedures for
copyrights defined in the Internet Standards process must be
followed, or as required to translate it into languages other than
English.
The limited permissions granted above are perpetual and will not be
revoked by the Internet Society or its successors or assigns.
This document and the information contained herein is provided on an
"AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Acknowledgement
Funding for the RFC Editor function is currently provided by the
Internet Society.