[ENH] Recommend controlled vocabulary for age Units, clarify that it can be overloaded

src/common-principles.md

@@ -1135,9 +1135,16 @@ Describing dates and timestamps:
     for more information.
 
 -   Age SHOULD be given as the number of years since birth at the time of
-    scanning (or first scan in case of multi session datasets). Using higher
-    accuracy (weeks) should in general be avoided due to privacy protection,
-    unless when appropriate given the study goals, for example, when scanning babies.
+    scanning (or first scan in case of multi session datasets).
+    The default unit is `"year"`, but it MAY be overridden in the JSON sidecar
+    (for example, `participants.json`) by setting `"Units"` to one of the
+    following values based on
+    [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601#Durations) duration
+    designators: `"year"`, `"month"`, `"week"`, `"day"`, `"hour"`, `"minute"`,
+    or `"second"`.
+    Using higher accuracy (for example, weeks or days) should in general be
+    avoided due to privacy protection, unless when appropriate given the study
+    goals, for example, when scanning babies or animals.
 
 ## Directory structure
 

src/schema/objects/columns.yaml

@@ -36,13 +36,15 @@ age:
   name: age
   display_name: Subject age
   description: |
-    Numeric value in years (float or integer value).
+    Numeric value (float or integer value).
+    By default expressed using "year" as the unit. Other possible "Units" are described in
+    [Units](SPEC_ROOT/common-principles.md#units).
 
-    For privacy purposes, participant ages should be capped at 89.
+    For privacy purposes, participant ages should be capped at 89 years.
     Using "89+" for ages above 88 is DEPRECATED.
   definition: {
     "LongName": "Subject age",
-    "Description": "Subject age in postnatal years",
+    "Description": "Subject postnatal age",
     "Format": "number",
     "Units": "year",
     "Maximum": 89,

src/schema/rules/checks/dataset.yaml

@@ -43,6 +43,21 @@ ParticipantIDMismatch:
         sorted(dataset.subjects.sub_dirs)
       )
 
+AgeUnits:
+  issue:
+    code: AGE_UNITS
+    message: |
+      The "Units" value for age in 'participants.json' is not a valid
+      ISO 8601-based duration unit.
+      Allowed values are "year", "month", "week", "day", "hour", "minute",
+      or "second".
+    level: warning
+  selectors:
+    - path == '/participants.tsv'
+    - '"Units" in sidecar.age'
+  checks:
+    - intersects([sidecar.age.Units], ["year", "month", "week", "day", "hour", "minute", "second"])
+
 # 214
 SamplesTSVMissing:
   issue: