update spec examples (HED)

[sappelhoff]

I think that the Bids spec should be updated in two places:

1. The section on 05-task-events has an example where it shows a sample events file with a trial_type column. It should include a json sidecar below it with the Levels defined for the trial_type. Researchers should be encouraged to provide sidecar information

2. The appendix on hed should be updated to show a json sidecar where my_codes has both Levels and HED descriptors. They should not be mutually exclusive. The current specification doesn't satisfy the common principles. The my_codes should have a LongName, Description, etc. since it corresponds to a name of a column.

Originally posted by @VisLab in bids-standard/bids-examples#191 (comment)

[VisLab]

I am trying to update this as part of the pull request #527, however I ran into a problem trying to understand the spec for tsv files given in Common Principles.

The example uses "test" as the key. What is the required relationship between this key and the columns of the spreadsheet and how does it relate to "LongName". Is "test" what appears in the spreadsheet? or is "LongName"? My assumption is that it is "test" that appears in the spreadsheet. If so, I think that the explanation for LongName in the table should be clarified. If not, I don't think the validators are looking for LongName?

[VisLab]

Also, the example doesn't show the Units or the URL. The spec should say what to do since the description above appears to say that all of these are required.

[sappelhoff]

Just to link: https://bids-specification.readthedocs.io/en/stable/02-common-principles.html#tabular-files

What is the required relationship between this key and the columns of the spreadsheet and how does it relate to "LongName".

the key is what is in the TSV, LongName is the unabbreviated name of the column ... for example bmi as the key, Body Mass Index as the LongName

If so, I think that the explanation for LongName in the table should be clarified.

Clarifications are always welcome in the form of a Pull Request 👍

The spec should say what to do since the description above appears to say that all of these are required.

Indeed, that'd be another welcome clarification. As it reads right now it's really unclear --> but for a fact, it's impossible to REQUIRE all of the fields, because a column in which you can define Units CANNOT logically have Levels.

I think the only REQUIRED field should be Description, the others should be RECOMMENDED/OPTIONAL.