Dates: format for the value and when attributes

date calendar AD and BC dates year month Gregorian calendar phrase-level encoding
dateStruct docDate dateRange

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:

The less precise components of a date (or time) may be missing for one of two reasons:

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:

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.


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>