Separate schema item definitions from layout rules

[tsalo]

Per today's NIDM-Terms call, one useful step toward integrating NIDM BIDS-Terms and the BIDS schema would be to divorce the layout rules (e.g., entity order in entities.yaml) from the definitions of the objects (e.g., the actual entities, their descriptions, etc.).

At the moment, I'm thinking something like this:

schema/
    entities.yaml: just a list of entities in order
    objects/
        sub.yaml: definition of the sub entity
        ses.yaml: definition of the ses entity
        ...
        split.yaml: definition of the split entity

[tsalo]

One thing that also came up is that it might be best to have the object definitions either in a single directory (regardless of class) or in a single file.

I think we'll need a key in the YAML files to denote the class of each item, such as "entity", "datatype", "suffix", and "metadata".

[tsalo]

While most elements in the specification are designed to have unique names, we do have several cases where data types (i.e., folders) and suffixes have the same names, such as "meg", "eeg", and "ieeg". I think most of the current BEPs follow the same pattern as well. This means placing all items in the same folder, regardless of their "class", will be a problem for these items specifically.

[yarikoptic]

re non-unique, my main question -- would they correspond to the same conceptual "item" even though possibly having multiple "classes"?

[tsalo]

I don't think so. While the main "modality" (i.e., suffix) is meg for the meg data type, for example, there are still other modalities that get placed in the meg folder.

On the other hand, we consider most (all?) of those other suffixes as "auxiliary", so... we might be able to say that the modality and data type versions refer to the same thing if "auxiliary data types" (should be "auxiliary modalities" now that I think of it) become a real concept instead of a useful trick to reduce duplication.

I'm leaning toward treating the homonymic data types and modalities as different for the sake of simplicity.

[yarikoptic]

I don't think so. While the main "modality" (i.e., suffix) is meg for the meg data type, for example, there are still other modalities that get placed in the meg folder.

But semantically it corresponds to the "magnetoencephalography" in either of those cases, right?

[tsalo]

Sorry, yes, that's correct.

[tsalo]

@yarikoptic in #762 I've realized that many metadata fields have different definitions based on the modality/section in which they're used. I think a reasonable solution is to have a "base" definition that can be extended on a table-wise basis within the specification. The base definition would be in the schema, while the extension would be in the macros call within the specification. Ultimately, we could probably incorporate those extensions/modifications into the schema, but it does mean that schema terms would be more than just a name and definition pair.

[tsalo]

After having worked on the metadata and suffix object definitions, I don't think we can use a single folder for all of them. Here's an updated proposal:

schema/
    rules/  # orders, requirement levels, relationships between objects
        entities.yaml
        datatypes/
            anat.yaml  # groups of suffixes and required entities, like we have now
    objects/  # these files would contain name, definition, and format info
        entities/
            subject.yaml
            ...
            description.yaml
        metadata/
            EchoTime.yaml
            ...
            RepetitionTime.yaml
        datatypes/
            anat.yaml  # just the name and definition