Dates: format for the value and when attributes
Encoding dates using date and the value (P4) or when (P5) attribute, including detailed instructions on the ISO 8601 standard for date values
Note: what was called the value attribute of date in P4 is called the when attribute in P5.
In TEI P5, the when attribute of date must be expressed using a W3C date format, which provides a standard machine-readable format for dates at many levels of specificity. We recommend using this standard even when using P4, because of the advantages it offers of consistency and processability. We list below for reference all of the different possibilities for capturing dates of various types, but not all of these will necessarily be dates you wish to encode with date. For instance, a reference like on the 24th of every month or the 20th century may not constitute a useful date within the context of your project, and if so can be ignored. You should think carefully how you will use the encoding (for instance, to generate time lines, to allow you to find all paragraphs or sections that reference a certain century, and so forth) before making a final decision.
The W3C date format takes the form of a four-digit year, followed
by a two-digit month and a two-digit day, separated by hyphens: e.g.,
1996-09-24. Portions of this date format may be omitted to express
dates with less precision; if information is omitted from the
left-hand side (i.e. the year, the year and month) then a placeholder
hyphen must be inserted. Here are examples:
- If the date is precise to the day:
1996-09-24 - If the date is precise to the month (e.g. Due in September 1996):
1996-09 - If the date is precise to the year (e.g. The 1996 campaign):
1996 - If the date incluces a time (e.g. Born 24 Sep 96 @ 3:25 a.m.):
1996-09-24T03:25:00
The less precise components of a date (or time) may be missing for one of two reasons:
- the date may be recurring, as in I have taken a day off from work every October 28th since 1988; or
- the year (or year & month) may be unknown, as in Supreme Court Trial part 102, Thursday, February 15
The W3C date formats provide a mechanism for encoding the first of these reasons (recurring dates), but not the latter (date is known, but year is not). It is expected that the TEI will develop a mechanism for encoding the latter sometime in the future, but not until after P5 1.0.
For expressing recurring dates, use hyphens as place-holders to mark omission of the less precise components, one hyphen per omitted component:
- A particular date, every year (e.g. 01 November):
--11-01 - A particular month, every year (e.g. September):
--09 - A particular day, every month (e.g. on the 24th of every month):
---24
Dates BCE are problematic. The W3C, and thus the TEI, currently indicate the year preceding year 0001 (i.e., 1 B.C.) as -0001, rather than as 0000 (or -0000). The latter is the format that astronomers and thus many other disciplines use. Thus for now the year 0000 is not permitted in a value of when (or notBefore, etc.), and the year 2 BCE should be represented with -0002. However, the W3C expects to remedy this in a future release of their specification, and the TEI intends to follow suit when that happens. At that point, the year 0000 will be a permissible value of when (indicating the year 1 BCE), and the year 2 BCE will be represented with -0001.
Date ranges can also be represented explicitly, as in the examples given below. In P5 you can also represent individual dates that fall at an unknown point within a range, using the notBefore and notAfter attributes; see example 3 below. For more detail on encoding date ranges, see Encoding date ranges.
Examples
Example 1 (P4)
A simple date with a regularized value:
<date value="1997-11-14">November 14, 1997</date>
Example 1 (P5)
A simple date with a regularized value:
<date when="1997-11-14">November 14, 1997</date>
Example 2 (P4)
A date that refers to an entire date range:
<date value="1997-11-14/1997-11-16">November 14 through 16, 1997</date>
Abbreviated version:
<date value="1997-11-14/16">November 14 through 16, 1997</date>
Example 2 (P5)
A date that refers to an entire date range:
<date from="1997-11-14" to="1997-11-16">November 14 through 16, 1997</date>
Example 3 (P5)
A date that refers to a sometime within a range:
<date notBefore="1997-11-14" notAfter="1997-11-16">Between 14 and 16 November 1997, inclusive</date>
Example 4
P4 — A date that refers to a month:
<date value="2003-11">November, 2003</date>
P5 — A date that refers to a month:
<date when="2003-11">November, 2003</date>