Currently, entities are defined in one section where they're used with a heading (which helps find the definition in the search bar), and are then referenced in all other sections where they're used. The problem is that this spreads those entity definitions out across various sections, with no interlinking between them, and with variable text at each location.

For example, the run entity is defined under "Anatomy imaging data" with the following:

If several scans of the same modality are acquired they MUST be indexed with a key-value pair: _run-1, _run-2, _run-3 etc. (only integers are allowed as run labels). When there is only one scan of a given type the run key MAY be omitted. Please note that diffusion imaging data is stored elsewhere (see below).

However, in the MEG and EEG sections, at least, the run entity is not defined. It is just used in the filename templates. I should note, though, that in most cases where a definition is included, it's the same as the main definition with the heading. This is good for the specification, but it requires good maintenance instead of being automated as it could be.

I propose that we move the "canonical" definitions to either one page for all of them or one page for each, and then include links to the entity definitions in specification text. This will (1) standardize the definitions and (2) prepare us for when entities must be defined only once, in a canonical manner, as in #540.

Alternatives to consider

• Link to entity definitions in the filename templates instead of, or in addition to, the specification text. Personally, I think this would be beautiful, but I don't think hyperlinks can be placed in code snippets.
• Use mdinclude or something similar to simply include the full definitions in all of the relevant sections of the specification text. I don't know how this would interact with pandoc or the search-bar, but it would be more readable.