ENH: Introduce GIFTI and CIFTI-2 formats in derivatives

src/02-common-principles.md

@@ -363,7 +363,7 @@ In particular, if a BIDS dataset contains a `derivatives/` subdirectory,
 the contents of that directory may be a heterogeneous mix of BIDS Derivatives
 datasets and non-compliant derivatives.
 
-## File Formation specification
+## File format specification
 
 ### Imaging files
 

src/05-derivatives/01-introduction.md

@@ -70,10 +70,77 @@ in [Derived dataset and pipeline description][derived-dataset-description].
     For example, if a summary statistic is derived from a given task, the file
     name SHOULD contain [`_task-<label>`](../appendices/entities.md#task).
 
+## File format specification
+
+Derived data may be resampled into structures that are not well-handled by the
+raw data formats.
+In this section, we describe standard formats that SHOULD be adhered to when
+appropriate, and the extensions they should have.
+
+### GIFTI Surface Data Format
+
+The [GIFTI][gifti] format is an XML-based structure containing one or more data arrays,
+and is well-suited to describing surface geometry and parcellations.
+
+The following extension table is reproduced in part from Section 9.0 of the
+[GIFTI specification][gifti-spec], indicating the expected extensions of different data arrays
+or combinations of data arrays.
+
+| Intent      | Extension     |
+|-------------|---------------|
+| Coordinates | `.coord.gii`  |
+| Functional  | `.func.gii`   |
+| Labels      | `.label.gii`  |
+| RGB or RGBA | `.rgba.gii`   |
+| Shape       | `.shape.gii`  |
+| Surface     | `.surf.gii`   |
+| Tensors     | `.tensor.gii` |
+| Time Series | `.time.gii`   |
+| Topology    | `.topo.gii`   |
+| Vector      | `.vector.gii` |
+
+Unless otherwise stated, bare `.gii` extensions SHOULD NOT be used
+for GIFTI files.
+
+### CIFTI-2 Connectivity File Formats
+
+The [CIFTI-2][cifti-2] family of connectivity file formats are NIfTI-2 files with an
+XML header extension describing up to three axes in the NIfTI data array.
+The NIfTI intent code indicates the type of data indicated in the array,
+and corresponds to a sequence of axes.
+
+For example, the `NIFTI_INTENT_CONNECTIVITY_DENSE_SERIES` indicates that
+the first axis has type `CIFTI_INDEX_TYPE_SERIES` and the second axis has
+type `CIFTI_INDEX_TYPE_BRAIN_MODELS`.
+The corresponding file extension is `.dtseries.nii`.
+
+The following tables is reproduced in part from Appendix A of the
+[CIFTI-2 Connectivity File Formats Appendices][cifti-appendix].
+
+| NIfTI Intent Code                              | Extension       |
+|------------------------------------------------|-----------------|
+| `NIFTI_INTENT_CONNECTIVITY_DENSE`              | `.dconn.nii`    |
+| `NIFTI_INTENT_CONNECTIVITY_DENSE_SERIES`       | `.dtseries.nii` |
+| `NIFTI_INTENT_CONNECTIVITY_PARCELLATED`        | `.pconn.nii`    |
+| `NIFTI_INTENT_CONNECTIVITY_PARCELLATED_SERIES` | `.ptseries.nii` |
+| `NIFTI_INTENT_CONNECTIVITY_DENSE_TRAJECTORY`   | `.dtraj.nii`    |
+| `NIFTI_INTENT_CONNECTIVITY_DENSE_SCALARS`      | `.dscalar.nii`  |
+| `NIFTI_INTENT_CONNECTIVITY_DENSE_LABELS`       | `.dlabel.nii`   |
+| `NIFTI_INTENT_CONNECTIVITY_PARCELLATED_SCALAR` | `.pscalar.nii`  |
+
+Unless otherwise stated, bare `.nii` extensions SHOULD NOT be used
+for CIFTI-2 files.
+
 <!-- Link Definitions -->
 
 [definitions]: ../02-common-principles.md#definitions
 
 [storage]: ../02-common-principles.md#storage-of-derived-datasets
 
 [derived-dataset-description]: ../03-modality-agnostic-files.md#derived-dataset-and-pipeline-description
+
+[gifti]: https://www.nitrc.org/projects/gifti/
+[cifti-2]: https://www.nitrc.org/projects/cifti/
+
+[gifti-spec]: https://www.nitrc.org/frs/download.php/2871/GIFTI_Surface_Format.pdf
+[cifti-appendix]: https://www.nitrc.org/forum/attachment.php?attachid=342&group_id=454&forum_id=1955