Revise section 4, include new subsection on leap seconds, define utc and tai calendars and leap_seconds in units_metadata

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:*
 
@@ -237,40 +237,59 @@ The values of **`var`** must be variables that exist in the file.
 
 [[section-13]]
 [[time-coordinate]]
-=== 4.4 Time Coordinate
+=== 4.4.1 Time Coordinate Units
 
 *Requirements:*
 
 * The time **`units`** of a time coordinate variable must contain a reference date/time.
-* The reference date/time of a time coordinate variable must be a legal date/time in the specified calendar.
-* The reference date/time in time **`units`** is not allowed to contain seconds equal to or greater than 60.
 
 *Recommendations:*
 
-* The use of time coordinates in year 0 and reference date/times in year 0 to indicate climatological time is deprecated.
 * Units of **`year`** and **`month`** and any equivalent units should be used with caution.
 * UDUNITS permits a number of alternatives to the word **`since`** in the units of time coordinates. All the alternatives have exactly the same meaning in UDUNITS. For compatibility with other software, CF strongly recommends that **`since`** should be used.
 
 [[section-14]]
 [[calendar]]
-=== 4.4.1 Calendar
+=== 4.4.2 Calendar
 
 *Requirements:*
 
-* The attributes **`calendar`**, **`month_lengths`**, **`leap_year`**, and **`leap_month`** may only be attached to time coordinate variables.
-* The standardized values (case insensitive) of the **`calendar`** attribute are **`standard`**, **`gregorian`** (deprecated), **`proleptic_gregorian`**, **`noleap`**, **`365_day`**, **`all_leap`**, **`366_day`**, **`360_day`**, **`julian`**, and **`none`**.
-If the **`calendar`** attribute is given a non-standard value, then the attribute **`month_lengths`** is required, along with **`leap_year`** and **`leap_month`** as appropriate.
-* The type of the **`month_lengths`** attribute must be an integer array of size 12.
-* The values of the **`leap_month`** attribute must be in the range 1-12.
-* The values of the **`leap_year`** and **`leap_month`** attributes are integer scalars.
+* The **`calendar`** attribute may only be attached to time coordinate variables.
+* If present, the value of the **`calendar`** attribute must be one of the standardized values (case insensitive) detailed in this section, unless the **`month_length`** attribute is present, in which case the **`calendar`** attribute must _not_ take one of the standardized values.
+* The reference date/time of a time coordinate variable must be a legal date/time in the specified calendar.
 
 *Recommendations:*
 
 * A time coordinate variable should have a **`calendar`** attribute.
+* If the **`calendar`** attribute is **`standard`**, **`gregorian**` (deprecated) or **`julian`** or absent, the use of time coordinates in year 0 and reference date/times in year 0 is deprecated.
 * The value **`standard`** should be used instead of **`gregorian`** in the **`calendar`** attribute.
-* 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.3 Leap Seconds
+
+*Requirements:*
+
+* The reference date/time in time **`units`** is not allowed to contain seconds equal to or greater than 60, except for valid leap seconds if the **`calendar`** is **`utc`**.
+* 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 if it has no **`calendar`** attribute, or if it has a **`calendar`** attribute with one of the following values: `standard`, `gregorian` (deprecated), `proleptic_gregorian`, `julian`.
+
+[[explicitly-defined-calendar]]
+=== 4.4.5 Explicitly Defined Calendar
+
+* The **`month_lengths`**, **`leap_year`**, and **`leap_month`** attributes may only be attached to time coordinate variables.
+* If the **`calendar`** attribute of a time coordinate variable is given a non-standard value, then the attribute **`month_lengths`** is required, along with **`leap_year`** and **`leap_month`** as appropriate.
+* The type of the **`month_lengths`** attribute must be an integer array of size 12.
+* The values of the **`leap_month`** attribute must be in the range 1-12.
+* The values of the **`leap_year`** and **`leap_month`** attributes are integer scalars.
+
+*Recommendations:*
+* The attribute **`leap_month`** should not appear unless the attribute **`leap_year`** is present.
+
 [[section-15]]
 [[coordinate-systems]]
 === 5 Coordinate Systems and Domain

history.adoc

@@ -7,6 +7,8 @@
 
 === Working version (most recent first)
 
+* {issues}542{Issue #542}: Clarify and rearrange text of section 4.4 about time coordinate units and calendars; introduce new text and a diagram explaining leap-seconds in existing calendars; define leap_second keyword of units_metadata attribute; define utc and tai calendars; define "date/time" in section 1.3.
+* {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.