Leap seconds

appa.adoc

@@ -386,8 +386,8 @@ In cases where there is a strong constraint on dataset size, it is allowed to pa
 | **`units_metadata`**
 | S
 | C, D, BI
-| <<units>>
-| Specifies the interpretation (on-scale, difference or unknown) of the unit of temperature appearing in the **`units`** attribute.
+| <<units>>, and <<time-coordinate>>
+| Specifies the interpretation of a unit of measure appearing in the **`units`** attribute.
 
 | **`valid_max`**
 | N

ch01.adoc

@@ -81,6 +81,8 @@ The coordinate values must be in strict monotonic order (all values are differen
 Missing values are not allowed in coordinate variables.
 To avoid confusion with coordinate variables, CF does not permit a one-dimensional string-valued variable to have the same name as its dimension.
 
+date/time:: The set of numbers which together identify an instant of time, namely its year, month, day, hour, minute and second, where the second may have a fraction but the others are all integer.
+
 grid mapping variable:: A variable used as a container for attributes that define a specific grid mapping.
 The type of the variable is arbitrary since it contains no data.
 

ch02.adoc

@@ -176,7 +176,7 @@ If it is observational, **`source`** should characterize it (e.g., "**`surface o
 
 **`history`**:: Provides an audit trail for modifications to the original data.
 Well-behaved generic netCDF filters will automatically append their name and the parameters with which they were invoked to the global history attribute of an input netCDF file.
-We recommend that each line begin with a timestamp indicating the date and time of day that the program was executed.
+We recommend that each line begin by indicating the date and time of day that the program was executed.
 
 **`references`**:: Published or web-based references that describe the data or methods used to produce it.
 

ch03.adoc

@@ -165,6 +165,11 @@ A standard name contains no whitespace and is case sensitive.
 canonical units:: Representative units of the physical quantity.
 Unless it is dimensionless, a variable with a **`standard_name`** attribute must have units which are physically equivalent (not necessarily identical) to the canonical units, possibly modified by an operation specified by the standard name modifier (see below and <<standard-name-modifiers>>) or by the **`cell_methods`** attribute (see <<cell-methods>> and <<appendix-cell-methods>>) or both.
 
+Units of time coordinates (<<time-coordinate>>), whose **`units`** attribute includes the word **`since`**, are _not_ physically equivalent to time units that do not include **`since`** in the **`units`**.
+To mark this distinction, the canonical unit given for quantities used for time coordinates is **`s since 1958-1-1`**.
+The choice of reference time and date (midnight on 1st January 1958) is arbitrary and not restrictive; the time coordinate variable's own **`units`** may contain any reference time and date (after **`since`**) that is valid in its calendar.
+In both kinds of time **`units`** attribute (with or without **`since`**), any unit for measuring time can be used i.e. any unit which is physically equivalent to the SI base unit of time, namely the second.
+
 description:: The description is meant to clarify the qualifiers of the fundamental quantities such as which surface a quantity is defined on or what the flux sign conventions are.
 We don't attempt to provide precise definitions of fundumental physical quantities (e.g., temperature) which may be found in the literature.
 The description may define rules on the variable type, attributes and coordinates which must be complied with by any variable carrying that standard name (such as in Example 3.5).

conformance.adoc

@@ -144,11 +144,11 @@ References can be absolute, relative or with no path, in which case, the variabl
 * The type of the **`units`** attribute is a string that must be recognizable by the UDUNITS package.
 Exceptions are the units **`level`**, **`layer`**, and **`sigma_level`**.
 * Dimensionless units for volume fractions defined by UDUNITS (**`ppv`**, **`ppmv`**, **`ppbv`**, **`pptv`**, **`ppqv`**) are not allowed in the **`units`** attribute of any variable which also has a **`standard_name`** attribute.
-* If present, the **`units_metadata`** attribute must have one of these values: `temperature: on_scale`, `temperature: difference`, `temperature: unknown`.
+* If present, the **`units_metadata`** attribute must have one of these values: `temperature: on_scale`, `temperature: difference`, `temperature: unknown`, `leap_seconds: none`, `leap_seconds: utc`, or `leap_seconds: unknown`.
 * The **`units`** of a variable that specifies a **`standard_name`** must be physically equivalent to the canonical units given in the standard name table, as modified by the **`standard_name`** modifier, if there is one, according to Appendix C, and then modified by all the methods listed in order by the **`cell_methods`** attribute, if one is present, according to Appendix E.
 * If the **`standard_name`** attribute includes the `standard_error` modifier, the **`units_metadata`** attribute, if present, must have the value `temperature: difference`.
-* If the **`cell_methods`** attribute includes any entry with any of the methods `range`, `standard_deviation` or `variance`, the **`units_metadata`** attribute, if present, must have the value `temperature: difference`.
-* A variable must not have a **`units_metadata`** attribute if it has no **`units`** attribute or if its **`units`** do not involve a temperature unit.
+* If a variable has a **`units`** attribute that involves a temperature unit, and has a **`cell_methods`** attribute includes any entry with any of the methods `range`, `standard_deviation` or `variance`, then the **`units_metadata`** attribute, if present, must have the value `temperature: difference`.
+* A variable must not have a **`units_metadata`** attribute if it has no **`units`** attribute, or if its **`units`** do not involve a temperature unit or a reference time unit.
 
 *Recommendations:*
 
@@ -271,6 +271,18 @@ If the **`calendar`** attribute is given a non-standard value, then the attribut
 * The attribute **`leap_month`** should not appear unless the attribute **`leap_year`** is present.
 * The time coordinate should not cross the date 1582-10-15 when the default mixed Gregorian/Julian calendar is in use.
 
+[[leap-seconds]]
+=== 4.4.2 Leap Seconds
+
+*Requirements:*
+
+* A time coordinate variable must not have a **`units_metadata`** attribute if it has a **`calendar`** attribute with a value _other than_ one of the following values: `standard`, `gregorian` (deprecated), `proleptic_gregorian`, `julian`.
+* If a time coordinate variable has a **`units_metadata`** attribute then it must have one of these values: `leap_seconds: none`, `leap_seconds: utc`, or `leap_seconds: unknown`.
+
+*Recommendations:*
+
+* A time coordinate variable should have a **`units_metadata`**  attribute when it has no **`calendar`** attribute, or has a **`calendar`** attribute with one of the following values: `standard`, `gregorian` (deprecated), `proleptic_gregorian`, `julian`.
+
 [[section-15]]
 [[coordinate-systems]]
 === 5 Coordinate Systems and Domain

history.adoc

@@ -7,6 +7,7 @@
 
 === Working version (most recent first)
 
+* {issues}166{Issue #166}: Clarify that time coordinate variables must have **`units`** containing **`since`** and a reference time; distinguish between canonical units of time with and without **`since`**.
 * {issues}403[Issue #403]: Metadata to encode quantization properties
 * {issues}530{Issue #530]: Define "the most rapidly varying dimension", and use this phrase consistently with the clarification "(the last dimension in CDL order)".
 * {issues}163[Issue #163]: Provide a convention for boundary variables for grids whose cells do not all have the same number of sides.

toc-extra.adoc

@@ -51,6 +51,7 @@ J.5. <<quadratic3>>
 4.4. <<time-axis-ex>>
 4.5. <<perpetual-time-axis-ex>>
 4.6. <<paleoclimate-time-axis-ex>>
+4.7. <<units-metadata-leap-seconds-ex>>
 5.1. <<independent-coordinate-variables-ex>>
 5.2. <<two-dimensional-coordinate-variables-ex>>
 5.3. <<reduced-horizontal-grid-ex>>