Enhance "JSON" documentations with new columns: "requirement level", "data type"

[sappelhoff]

Whenever we describe JSON files in the BIDS specification, we usually do it using a FieldName and a Definition column (see e.g., dataset_description.json):

FieldName	Definition
Authors	OPTIONAL. List of individuals who contributed to the creation/curation of the dataset.

In terms of JSON, the FieldName is relatively uncontroversial. It must be a key in the JSON file, formatted like this:

{
  "Authors": 
}

However, what's happening in Definition is a lot more to handle. I suggest to change the way we describe JSON files to the following:

FieldName	Req. Level	Datatype	Definition
Authors	OPTIONAL	array of string	List of individuals who contributed to the creation/curation of the dataset.

• This would make it easier to parse the requirement level (optional, required, recommended)
• This would make clear how to format the field ... solving and preventing issues like RepetitionTime type in bold.json not specified. #516 --> also, bids-validator devs can more easily adopt the spec in terms of JS code

I propose this enhancement "as is" ... but for the future, we may also consider turning these tables into YML format, like @tsalo is currently doing with the entity table in #475 (BTW: please review that PR!)

[tsalo]

This is somewhat related to #221, which proposes adding a "Type"/"Datatype" field directly to the jsons. I think specifying the required data type in the schema and documentation would eliminate the need for a field specifying type on a file-by-file basis in the jsons, right?

EDIT: Also related to #350.

[sappelhoff]

I think specifying the required data type in the schema and documentation would eliminate the need for a field specifying type on a file-by-file basis in the jsons, right?

you mean in the JSON schemas that the bids-validator uses? https://github.com/bids-standard/bids-validator/tree/master/bids-validator/validators/json/schemas

and with "specifying in the documentation" I assume that you mean doing what I hint at in the original post of this thread?

If I understand you correctly, then yes I would agree that these two aspects are sufficient and we can close #221

[tsalo]

@sappelhoff Yes, sorry for the poor wording. That's exactly what I mean, although bids-validator JSON schema will of course become bids-specification schema if and when we have that implemented. If your recommendation is accepted (as I hope it will be), we can also close #350.

[sappelhoff]

Once this PR is done, we can also transfer the benefits over to the validator --> e.g., here: https://github.com/bids-standard/bids-validator/issues/851