columns.yml: unclear difference in schema in defining within record or within "definition" sub-record

[yarikoptic]

In https://github.com/bids-standard/bids-specification/blob/HEAD/src/schema/objects/columns.yaml we have

duration:
  name: duration
  display_name: Event duration
  description: |
    Duration of the event (measured from onset) in seconds.
    Must always be either zero or positive (or `n/a` if unavailable).
    A "duration" value of zero implies that the delta function or event is so
    short as to be effectively modeled as an impulse.
  type: number 
  unit: s
  minimum: 0

where there is type and unit within the record but then there is

age:
  name: age
  display_name: Subject age
  description: |
    Numeric value in years (float or integer value).
  
    It is recommended to tag participant ages that are 89 or higher as 89+,
    for privacy purposes.
  definition: {
    "LongName": "Subject age",
    "Description": "Subject age in postnatal years",
    "Units": "year",
  }

where there is definition field with "Units" in it. I found no mentioning of definition: within https://github.com/bids-standard/bids-specification/tree/master/src/schema README.

• is such difference warranted or should we seek to unify by either abolishing definition and moving all into the record or unifying into everything having definition?
  • why unit vs Units difference? very loosely related https://github.com/bids-standard/bids-2-devel/issues/15
  • and overall why in "definition" attributes are Capitalized?
• why definition is in JSON syntax (subclass of YAML, I know) and not regular YAML?

If not to be changed anyhow, should be addressed by clarifications within https://github.com/bids-standard/bids-specification/blob/master/src/schema/README.md .

[effigies]

• https://github.com/bids-standard/bids-specification/pull/1838

[effigies]

I agree we should update the README, and that should have been part of that PR.