diff --git a/.codespellrc b/.codespellrc
index 9a3c973eab..c9b7d937a2 100644
--- a/.codespellrc
+++ b/.codespellrc
@@ -1,7 +1,7 @@
 [codespell]
 skip = *.js,*.svg,*.eps,.git,node_modules,env,venv,.mypy_cache,package-lock.json,CITATION.cff,tools/new_contributors.tsv,./tools/schemacode/docs/build,venvs
 ignore-regex = \bHEP\b
-ignore-words-list = acknowledgements,als,bu,fo,te,weill,winn
+ignore-words-list = acknowledgements,als,bu,fo,te,weill,winn,burnin
 builtin = clear,rare,en-GB_to_en-US
 # this overloads default dictionaries and I have not yet figured out
 # how to have multiple https://github.com/codespell-project/codespell/issues/2727
diff --git a/mkdocs.yml b/mkdocs.yml
index b860d6ca9e..f73b6b4c93 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -28,6 +28,7 @@ nav:
           - BIDS Derivatives: derivatives/introduction.md
           - Common data types and metadata: derivatives/common-data-types.md
           - Imaging data types: derivatives/imaging.md
+          - Diffusion MRI: derivatives/diffusion-derivatives.md
       - Longitudinal and multi-site studies: longitudinal-and-multi-site-studies.md
       - Glossary: glossary.md
       - BIDS Extension Proposals: extensions.md
@@ -156,6 +157,7 @@ plugins:
         "05-derivatives/01-introduction.md": "derivatives/introduction.md"
         "05-derivatives/02-common-data-types.md": "derivatives/common-data-types.md"
         "05-derivatives/03-imaging.md": "derivatives/imaging.md"
+        "05-derivatives/04-diffusion.md": "derivatives/diffusion-derivatives.md"
         "06-longitudinal-and-multi-site-studies.md": "longitudinal-and-multi-site-studies.md"
         "07-extensions.md": "extensions.md"
         "99-appendices/14-glossary.md": "glossary.md"
diff --git a/src/derivatives/diffusion-derivatives.md b/src/derivatives/diffusion-derivatives.md
new file mode 100644
index 0000000000..8ccca51724
--- /dev/null
+++ b/src/derivatives/diffusion-derivatives.md
@@ -0,0 +1,1096 @@
+# Diffusion derivatives
+
+## Preprocessed diffusion-weighted images
+
+-   As with [raw diffusion imaging data](../modality-specific-files/magnetic-resonance-imaging-data.md#required-gradient-orientation-information),
+    inclusion of gradient orientation information is REQUIRED. While
+    [the inheritance principle](../common-principles.md#the-inheritance-principle)
+    applies, it is common for DWI preprocessing to include rotation of
+    gradient orientations according to subject motion, so series-specific
+    gradient information is typically expected.
+
+-   As per [file naming conventions for BIDS Derivatives](introduction.md#file-naming-conventions),
+    preprocessed DWI data must not possess the same name as that of the raw
+    DWI data. It is RECOMMENDED to disambiguate through use of the key-value
+    "`_desc-preproc`".
+
+-   As per [common data types](common-data-types.md) for derivative data, a
+    JSON sidecar file is REQUIRED due to the REQUIRED `SkullStripped` field.
+
+<!--
+This block generates a filename templates.
+The inputs for this macro can be found in the directory
+  src/schema/rules/files/deriv
+and a guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
+{{ MACROS___make_filename_template(
+    "deriv",
+    placeholders=True,
+    show_entities=["space", "model", "parameter", "description", "resolution"],
+    suffixes=["dwimap", "dwi"],
+) }}
+
+Manual:
+
+```Text
+<pipeline_name>/
+    sub-<label>/
+        [ses-<label>/]
+            dwi/
+                <source-entities>[_space-<space>]_desc-preproc_dwi.nii[.gz]
+                <source-entities>[_space-<space>]_desc-preproc_dwi.bval
+                <source-entities>[_space-<space>]_desc-preproc_dwi.bvec
+                <source-entities>[_space-<space>]_desc-preproc_dwi.json
+```
+
+## Diffusion models
+
+Diffusion MRI can be modeled using various paradigms
+to extract more informative representations of the diffusion process
+and the underlying biological structure.
+There are two key attributes of diffusion models
+that warrant explicit mention due to their consequence in how they are represented:
+
+-   The encoding of *anisotropic* information;
+    that is, quantities for which the value depends on the orientation in which it is sampled.
+    Much of the detail in diffusion derivatives is therefore dedicated
+    to the definition of how such data are serialized into corresponding NIfTI images,
+    and how corresponding metadata is used to facilitate correct interpretation of those data.
+
+-   A diffusion model may represent the contents of each image voxel as the sum of *multiple compartments*;
+    further, each of these different compartments may have different intrinsic properties,
+    such as units or anisotropy (as above).
+    An individual model fit may therefore yield data for its different parameters
+    distributed across multiple NIfTI images,
+    and each image may require unique metadata fields to facilitate interpretation.
+
+### Basic filesystem structure
+
+```Text
+<pipeline_name>/
+    sub-<label>/
+        [ses-<label>/]
+            dwi/
+                <source-entities>[_space-<space>]_model-<label>_param-<label1>[_desc-<label>]_dwimap.nii[.gz]
+                <source-entities>[_space-<space>]_model-<label>_param-<label1>[_desc-<label>]_dwimap.json
+                <source-entities>[_space-<space>]_model-<label>_param-<label2>[_desc-<label>]_dwimap.nii[.gz]
+                <source-entities>[_space-<space>]_model-<label>_param-<label2>[_desc-<label>]_dwimap.json
+                <source-entities>[_space-<space>]_model-<label>_param-<label3>[_desc-<label>]_dwimap.nii[.gz]
+                <source-entities>[_space-<space>]_model-<label>_param-<label3>[_desc-<label>]_dwimap.json
+```
+
+-   Files "`<source-entities>_model-<label>_param-<label*>_dwimap.nii[.gz]`"
+    provide image data encoding the different parameters that may be estimated by the model.
+    If the image is a three-dimensional volume,
+    then in the absence of any metadata indicating to the contrary,
+    the image should be interpreted as yielding a single scalar parameter per voxel.
+    If the image is of a higher dimensionality,
+    then relevant metadata fields MUST be specified in the corresponding sidecar JSON file
+    indicating how data across dimensions beyond the three spatial dimensions
+    should be interpreted.
+
+-   Files "`<source-entities>_model-<label>_param-<label*>_dwimap.json`"
+    MUST provide information about the model,
+    and SHOULD provide information about how it was fit to the empirical image data.
+    In circumstances where the dimensionality of the corresponding NIfTI image is greater than three,
+    they MUST also specify requisite metadata fields regarding
+    how data across dimensions beyond the three spatial dimensions are to be interpreted.
+
+### Orientation encoding types
+
+There are many mathematical bases that may be used
+in the encoding of parameters that vary as a function of orientation.
+A list of such functions supported by the specification is enumerated below,
+accompanied by requisite information specific to each representation.
+
+For image data that encode orientation information,
+there are fields that MUST be specified in the sidecar JSON file
+in order to ensure appropriate interpretation of that information;
+see [parameter metadata](#parameter-metadata).
+
+1.  <a name="encoding-scalar">*Scalar image*</a>:
+
+    Image data that do not encode orientation information
+    are referred to henceforth here as "scalar" parameters.
+
+1.  <a name="encoding-dec">*Directionally-Encoded Colors (DEC)*</a>:
+
+    An image with three volumes,
+    intended to be interpreted as red, green and blue color intensities for visualization.
+    Image data MUST NOT contain negative values.
+
+1.  <a name="encoding-spherical">*Spherical coordinates*</a>:
+
+    An image where data across volumes within each voxel encode
+    one or more discrete orientations using angles on the 2-sphere,
+    optionally encoding some parameter as the distance from origin.
+
+    This may take one of two forms:
+
+    1.  Value per direction
+
+        Each consecutive triplet of image volumes encodes a 3-tuple spherical coordinate,
+        using ISO convention for both the order of parameters
+        and reference frame for angles:
+
+        1.  Distance from origin,
+            encoding some non-negative parameter of interest.
+
+        1.  Inclination / polar angle in radians,
+            relative to the zenith direction being the positive direction of the *third* reference axis
+            (see [parameter metadata](#parameter-metadata));
+
+        1.  Azimuth angle, in radians,
+            orthogonal to the zenith direction,
+            with value of 0.0 corresponding to the *first* reference axis
+            (see [parameter metadata](#parameter-metadata)),
+            increasing toward the positive direction of the *second* reference axis.
+
+        Number of image volumes is equal to (3x*N*),
+        where *N* is the maximum number of discrete orientations in any voxel in the image.
+
+    1.  Orientations only
+
+        Each consecutive pair of image volumes encodes an inclination / azimuth pair,
+        with order & convention identical to that above
+        (equivalent to spherical coordinate with assumed unity distance from origin).
+
+        Number of image volumes is equal to (2x*N*), where *N* is the maximum
+        number of discrete orientations in any voxel in the image.
+
+1.  <a name="encoding-3vector">*3-Vectors*</a>:
+
+    An image where data across volumes within each voxel encode
+    one or more discrete orientations
+    using triplets of axis dot products.
+
+    This may take one of two forms:
+
+    1.  Value per orientation
+
+        The *norm* of the 3-vector encodes some non-negative parameter of interest,
+        while its normalized form encodes an orientation on the unit sphere.
+
+    1.  Orientations only
+
+        Each triplet of values encodes an orientation on the unit sphere
+        (that is, the vector norm MUST be 1.0);
+        no quantitative value is associated with each orientation.
+
+    Number of image volumes is equal to (3x*N*),
+    where *N* is the maximum number of discrete orientations in any voxel in the image.
+
+1.  <a name="encoding-tensor">*Tensor*</a>:
+
+    An image where volumes encode coefficients of a tensor.
+
+    -   For *Rank 2* tensors:
+
+        If antipodal symmetry is set (or implicitly assumed),
+        then the image MUST contain six volumes, in the order:
+        *D<sub>11</sub>*, *D<sub>12</sub>*, *D<sub>13</sub>*, *D<sub>22</sub>*, *D<sub>23</sub>*, *D<sub>33</sub>,
+        where *1*, *2* and *3* index the three spatial dimensions according to their reference
+        (see field `"OrientationEncoding"["Reference"]` in [parameter metadata](#parameter-metadata)).
+        If the data are not antipodally symmetric,
+        then the image MUST contain nine volumes, in the order:
+        *D<sub>11</sub>*, *D<sub>12</sub>*, *D<sub>13</sub>*, *D<sub>21</sub>*, *D<sub>22</sub>*, *D<sub>23</sub>, *D<sub>31</sub>*, *D<sub>32</sub>*, *D<sub>33</sub>,
+        with subscripts indexing row then column.
+
+1.  <a name="encoding-sh">*Spherical Harmonics (SH)*</a>:
+
+    Image where data across volumes within each voxel encode
+    a continuous function spanning the 2-sphere
+    using coefficients within a spherical harmonics basis.
+
+    Number of image volumes depends on the spherical harmonic basis employed,
+    and the maximal spherical harmonic degree *l<sub>max</sub>*
+    (see [spherical harmonics bases](#spherical-harmonics-bases)).
+
+1.  <a name="encoding-amp">*Amplitudes*</a>:
+
+    Image where data across volumes within each voxel encode
+    amplitudes of a discrete function spanning the 2-sphere.
+
+    Number of image volumes corresponds to the number of discrete orientations
+    on the unit sphere along which samples for the spherical function in
+    each voxel are provided;
+    these orientations MUST themselves be provided in the associated sidecar JSON file
+    (see [parameter metadata](#parameter-metadata)).
+
+### Bootstrap encoding
+
+For some models,
+it is common to export not only the best fit of the model to the empirical data,
+but multiple realizations of that fit taking into account image noise,
+typically through some form of bootstrapping procedure.
+Where this occurs,
+the image data for each parameter possess an additional dimension,
+along which those multiple realizations are stored.
+
+For some models,
+it is common to explicitly store *both* the multiple realizations of the model
+*and* either the parameters corresponding to the maximum *a posteriori* fit
+or the mean of each parameter computed across those realizations.
+In these circumstances,
+it is RECOMMENDED to use the same label for the "`_model-`" entity,
+and use the "`_desc-`" entity to disambiguate between these two versions
+at the filesystem level.
+
+### Metadata fields
+
+#### Model vs. parameter metadata
+
+For a NIfTI image that encodes some parameter of some model,
+there are are range of metadata fields that may be relevant.
+These can be broadly separated into two categories:
+
+1.  Metadata that apply to *the model as a whole*
+    are not specific to any individual parameter estimated by that model.
+    It is therefore RECOMMENDED that any such metadata
+    be *equivalent* across all sidecar JSON files for all parameters of that model.
+
+1.  Metadata that apply *only to that specific parameter*
+    may include attributes such as units and orientation encoding
+    essential for correct interpretation of that parameter image *only*.
+    it is therefore possible that these metadata fields may *differ*
+    across the multiple parameters estimated by that model.
+
+#### Model metadata
+
+At the root of the metadata dictionary,
+REQUIRED field `"Model"` defines a dictionary that contains relevant information
+about what the model is and how it was fit to empirical image data.
+The following table defines reserved fields within the `"Model"` sub-dictionary.
+
+{{ MACROS___make_subobject_table("metadata.Model") }}
+
+Dictionary `"Model["Parameters"]"` has the following reserved keywords that may be applicable to a broad range of models:
+
+{{ MACROS___make_subobject_table("metadata.Model.properties.Parameters") }}
+
+#### Parameter metadata
+
+The following tables define reserved fields relevant to individual model parameters.
+
+Some fields are relevant only to specific [orientation encoding types](#orientation-encoding-types):
+
+-   Where a field *is* relevant for the corresponding image,
+    designators OPTIONAL and REQUIRED within the "Description" column apply.
+
+-   Where a field is *not* relevant for the corresponding image,
+    that metadata field MUST NOT be specified.
+
+Auto-generated table:
+
+{{ MACROS___make_metadata_table(
+    {
+        "BootstrapAxis": ("OPTIONAL", "Applicable to any orientation encoding type."),
+        "Description": ("OPTIONAL", "Applicable to any orientation encoding type."),
+        "NonNegativity": ("OPTIONAL", "Applicable to all orientation encoding types except [spherical coordinates](#encoding-spherical) and [3-vectors](#encoding-3vector)."),
+        "OrientationEncoding": ("REQUIRED", "Applicable to any orientation encoding type."),
+        "ParameterURL": ("OPTIONAL", "Applicable to any orientation encoding type."),
+        "ResponseFunction": ("OPTIONAL", "Applicable to [spherical harmonics](#encoding-sh)."),
+    }
+) }}
+
+Manual table:
+
+| **Key name**        | Relevant [orientation encoding types](#orientation-encoding-types)                         | **Description**                                                                                                                                                                                                                       |
+| ------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| BootstrapAxis       | Any                                                                                        | OPTIONAL. Integer. If multiple realizations of a given parameter are stored in a NIfTI image, this field nominates the image axis (indexed from zero) along which those multiple realizations are stored.                             |
+| Description         | Any                                                                                        | OPTIONAL. String. Text description of what model parameter is encoded in the corresponding data file.                                                                                                                                 |
+| NonNegativity       | All except [spherical coordinates](#encoding-spherical) and [3-vectors](#encoding-3vector) | OPTIONAL. String. Options are: { `regularized`, `constrained` }. Specifies whether, during model fitting, the parameter was regularized to not take extreme negative values, or was explicitly forbidden from taking negative values. |
+| OrientationEncoding | Any                                                                                        | REQUIRED if dimensionality of NIfTI image is greater than three. Dictionary. Provides information requisite to the interpretation of orientation information encoded in each voxel; more details below.                               |
+| ParameterURL        | Any                                                                                        | OPTIONAL. String. URL to documentation that describes the specific model parameter that is encoded within the data file.                                                                                                              |
+| ResponseFunction    | [Spherical harmonics](#encoding-sh)                                                        | OPTIONAL. Dictionary. Specifies a response function that was utilized by a deconvolution algorithm; more details below.                                                                                                               |
+
+Dictionary `"OrientationEncoding"` has the following reserved keywords:
+
+{{ MACROS___make_subobject_table("metadata.OrientationEncoding") }}
+
+The following fields should only be present when `OrientationEncoding.Type` is `"amplitudes"`:
+
+<!-- This block generates a metadata table.
+These tables are defined in
+  src/schema/rules/sidecars
+The definitions of the fields specified in these tables may be found in
+  src/schema/objects/metadata.yaml
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
+{{ MACROS___make_sidecar_table([
+    "derivatives.diffusion.OrientationEncodingTypeAmplitudes",
+]) }}
+
+The following fields should only be present when `OrientationEncoding.Type` is `"sh"`:
+
+<!-- This block generates a metadata table.
+These tables are defined in
+  src/schema/rules/sidecars
+The definitions of the fields specified in these tables may be found in
+  src/schema/objects/metadata.yaml
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
+{{ MACROS___make_sidecar_table([
+    "derivatives.diffusion.OrientationEncodingTypeSphericalHarmonics",
+]) }}
+
+The following fields should only be present when `OrientationEncoding.Type` is `"tensor"`:
+
+<!-- This block generates a metadata table.
+These tables are defined in
+  src/schema/rules/sidecars
+The definitions of the fields specified in these tables may be found in
+  src/schema/objects/metadata.yaml
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
+{{ MACROS___make_sidecar_table([
+    "derivatives.diffusion.OrientationEncodingTypeTensor",
+]) }}
+
+The following fields should only be present when `OrientationEncoding.Type` is not `"scalar"`:
+
+<!-- This block generates a metadata table.
+These tables are defined in
+  src/schema/rules/sidecars
+The definitions of the fields specified in these tables may be found in
+  src/schema/objects/metadata.yaml
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
+{{ MACROS___make_sidecar_table([
+    "derivatives.diffusion.OrientationEncodingTypeNotScalar",
+]) }}
+
+Manual table:
+
+| **Key name**            | Relevant [orientation encoding types](#orientation-encoding-types)                                                                                                         | **Description**                                                                                                                                                                                                                                                                                                                                                                                                              |
+| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| AmplitudesDirections    | [Amplitudes](#encoding-amp)                                                                                                                                                | REQUIRED for `"Type": "amplitudes"`; MUST NOT be specified otherwise. List of lists of floats. Data are either [spherical coordinates (directions only)](#encoding-spherical) or [3-vectors](#encoding-3vector) with unit norm. Defines the dense directional basis set on which samples of a spherical function within each voxel are provided. The length of the list must be equal to the number of volumes in the image. |
+| AntipodalSymmetry       | [spherical coordinates](#encoding-spherical), [3-vectors](#encoding-3vector), [tensor](#encoding-tensor), [amplitudes](#encoding-amp), [spherical harmonics](#encoding-sh) | OPTIONAL. Boolean. Indicates whether orientation information should be interpreted as being antipodally symmetric. Assumed to be True if omitted.                                                                                                                                                                                                                                                                            |
+| EncodingAxis            | All except [scalar](#encoding-scalar)                                                                                                                                      | REQUIRED. Integer. Indicates the image axis (indexed from zero) along which image intensities should be interpreted as corresponding to orientation encoding.                                                                                                                                                                                                                                                                |
+| FillValue               | [Scalar](#encoding-scalar), [spherical coordinates](#encoding-spherical), [3-vectors](#encoding-3vector)                                                                   | OPTIONAL. Float; allowed values: { 0.0, NaN }. Value stored in image when the number of discrete orientations in a given voxel is fewer than the maximal number for that image.                                                                                                                                                                                                                                              |
+| Reference               | All except [scalar](#encoding-scalar)                                                                                                                                      | REQUIRED. String; allowed values: { `bvec`, `ijk`, `xyz` }. Defines the reference coordinate system against which orientation information is encoded (more below).                                                                                                                                                                                                                                                           |
+| SphericalHarmonicBasis  | [Spherical harmonics](#encoding-sh)                                                                                                                                        | REQUIRED for `"Type": "sh"`; MUST NOT be specified otherwise. String. Options are: { `mrtrix3`, `descoteaux` }. Details are provided in the [spherical harmonics bases](#spherical-harmonics-bases) section.                                                                                                                                                                                                                 |
+| SphericalHarmonicDegree | [Spherical harmonics](#encoding-sh)                                                                                                                                        | OPTIONAL for `"Type": "sh"`; MUST NOT be specified otherwise. Integer. The maximal spherical harmonic order *l<sub>max</sub>*; the number of volumes in the associated NIfTI image must correspond to this value as per the relationship described in [spherical harmonics bases](#spherical-harmonics-bases) section.                                                                                                       |
+| TensorRank              | [Tensor](#encoding-tensor)                                                                                                                                                 | REQUIRED for `"Type": "tensor"; MUST NOT be specified otherwise. Integer. Rank of tensor reporesentation. Specification currently only supports a value of 2.                                                                                                                                                                                                                                                                |
+| Type                    | Any                                                                                                                                                                        | REQUIRED. String. Specifies the type of orientation information (if any) encoded in the NIfTI image. Permitted values: { `scalar`, `dec`, `unitspherical`, `spherical`, `unit3vector`, `3vector`, `tensor`, `sh`, `amplitudes` }.                                                                                                                                                                                            |
+
+Field `"OrientationEncoding"["Reference"]` MUST contain one of the following values:
+
+| **Key name** | **LongName** | **Description**                                                                                                                                                                                                                                                               |
+| ------------ | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| bvec         | bvec         | The three spatial image axes; **unless** those axes form a right-handed coordinate system (that is, the 3x3 linear component of the NIfTI header transformation has a positive determinant), in which case the negative of the first axis orientation is the first reference. |
+| ijk          | ijk          | The three spatial image axes define the orientation.                                                                                                                                                                                                                          |
+| xyz          | xyz          | The 'real' / 'scanner' space axes, which are independent of the NIfTI image header transform, define the orientation reference.                                                                                                                                               |
+
+Dictionary `"ResponseFunction"` has the following reserved keywords:
+
+Auto-generated table:
+
+{{ MACROS___make_subobject_table("metadata.ResponseFunction") }}
+
+Manual table:
+
+| **Key name** | **LongName** | **Description**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| ------------ | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| coefficients | coefficients | REQUIRED. Either a list of floats, or a list of lists of floats, depending on the mathematical form of the response function and possibly the data to which it applies; see further below.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| type         | type         | REQUIRED. String. The mathematical form in which the response function coefficients are provided; see further below. Levels are "eigen" (list of 4 floating-point values must be specified; these are interpreted as three ordered eigenvalues of a rank 2 tensor, followed by a reference *b*=0 intensity.) and "zsh" (Either of (1) a list of floating-point values: Values correspond to the response function coefficient for each consecutive even zonal spherical harmonic degree starting from zero; OR (2) List of lists of floating-point values. One list per unique *b*-value. Each individual list contains a coefficient per even zonal spherical harmonic degree starting from zero. If the response function utilized has a different number of non-zero zonal spherical harmonic coefficients for different *b*-values, these must be padded with zeroes such that all lists contain the same number of floating-point values.) |
+
+### Demonstrative examples
+
+#### A basic Diffusion Tensor fit
+
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
+{{ MACROS___make_filetree_example(
+    {
+        "dti_pipeline": {
+            "sub-01": {
+                "dwi": {
+                    "sub-01_model-tensor_param-diffusivity_dwimap.nii.gz": "",
+                    "sub-01_model-tensor_param-diffusivity_dwimap.json": "",
+                    "sub-01_model-tensor_param-s0_dwimap.nii.gz": "",
+                    "sub-01_model-tensor_param-s0_dwimap.json": "",
+                    "sub-01_model-tensor_param-fa_dwimap.nii.gz": "",
+                    "sub-01_model-tensor_param-fa_dwimap.json": "",
+                },
+            },
+        },
+    }
+) }}
+
+Dimensions of NIfTI image "`sub-01_model-tensor_param-diffusivity_dwimap.nii.gz`": *I*x*J*x*K*x6 ([symmetric rank 2 tensor image](#encoding-tensor))
+
+Dimensions of NIfTI image "`sub-01_model-tensor_param-s0_dwimap.nii.gz`": *I*x*J*x*K* ([scalar](#encoding-scalar))
+
+Dimensions of NIfTI image "`sub-01_model-tensor_param-fa_dwimap.nii.gz`": *I*x*J*x*K* ([scalar](#encoding-scalar))
+
+Contents of file `sub-01_model-tensor_param-diffusivity_dwimap.json`:
+
+```JSON
+{
+    "Description": "Diffusion Coefficient, encoded as a tensor representation",
+    "Model": {
+        "Description": "Diffusion Tensor",
+        "Parameters": {
+            "FitMethod": "ols",
+            "OutlierRejectionMethod": "None"
+        }
+    },
+    "OrientationEncoding": {
+        "AntipodalSymmetry": true,
+        "EncodingAxis": 3,
+        "Reference": "xyz",
+        "TensorRank": 2,
+        "Type": "tensor"
+    },
+    "Units": "mm^2/s"
+}
+```
+
+Contents of file `sub-01_model-tensor_param-s0_dwimap.json`:
+
+```JSON
+{
+    "Description": "Estimated signal intensity with no diffusion weighting, ie. S0",
+    "Model": {
+        "Description": "Diffusion Tensor",
+        "Parameters": {
+            "FitMethod": "ols",
+            "OutlierRejectionmethod": "None"
+        }
+    }
+}
+```
+
+Contents of file `sub-01_model-tensor_param-fa_dwimap.json`:
+
+```JSON
+{
+    "Description": "Fractional Anisotropy",
+    "Model": {
+        "Description": "Diffusion Tensor",
+        "Parameters": {
+            "FitMethod": "ols",
+            "OutlierRejectionmethod": "None"
+        }
+    },
+    "ParameterURL": "https://doi.org/10.1002/nbm.1940080707"
+}
+```
+
+Notes:
+
+-   "The diffusion tensor" intrinsically is a mathematical model of how
+    the diffusivity is estimated to vary as a function of orientation.
+    As such, within this model,
+    it is not the *parameter* that is a tensor;
+    rather, it is the *diffusivity* that is the estimated parameter,
+    and the *way in which the anisotropy of that parameter is encoded* is a tensor.
+
+-   Even if image `sub-01_model-tensor_param-diffusivity_dwimap.nii.gz`
+    were to be the only image yielded by the pipeline,
+    it is nevertheless REQUIRED to include entity "`_param-`" in those file names.
+
+-   Metadata fields relevant to the interpretation of the anisotropy of the tensor
+    are *not relevant* to the scalar measures
+    "`s0`" (estimated signal intensity with no diffusion weighting)
+    or "`fa`" (Fractional Anisotropy).
+    Those fields therefore MUST be omitted from the corresponding sidecar JSONs.
+
+#### A multi-shell, multi-tissue Constrained Spherical Deconvolution fit
+
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
+{{ MACROS___make_filetree_example(
+    {
+        "msmtcsd_pipeline": {
+            "sub-01": {
+                "dwi": {
+                    "sub-01_model-csd_param-wm_dwimap.nii.gz": "",
+                    "sub-01_model-csd_param-wm_dwimap.json": "",
+                    "sub-01_model-csd_param-gm_dwimap.nii.gz": "",
+                    "sub-01_model-csd_param-gm_dwimap.json": "",
+                    "sub-01_model-csd_param-csf_dwimap.nii.gz": "",
+                    "sub-01_model-csd_param-csf_dwimap.nii.gz": "",
+                },
+            },
+        },
+    }
+) }}
+
+Dimensions of NIfTI image "`sub-01_model-csd_param-wm_dwimap.nii.gz`": *I*x*J*x*K*x45 ([spherical harmonics](#encoding-sh))
+
+Dimensions of NIfTI image "`sub-01_model-csd_param-gm_dwimap.nii.gz`": *I*x*J*x*K*x1 ([spherical harmonics](#encoding-sh))
+
+Dimensions of NIfTI image "`sub-01_model-csd_param-csf_dwimap.nii.gz`": *I*x*J*x*K*x1 ([spherical harmonics](#encoding-sh))
+
+Contents of JSON file "`sub-01_model-csd_param-wm_dwimap.json`":
+
+```JSON
+{
+    "Model": {
+        "Description": "Multi-Shell Multi-Tissue (MSMT) Constrained Spherical Deconvolution (CSD)",
+        "URL": "https://mrtrix.readthedocs.io/en/latest/constrained_spherical_deconvolution/multi_shell_multi_tissue_csd.html",
+    },
+    "Description": "White matter",
+    "NonNegativity": "constrained",
+    "OrientationEncoding": {
+        "EncodingAxis": 3,
+        "Reference": "xyz",
+        "SphericalHarmonicBasis": "MRtrix3",
+        "SphericalHarmonicDegree": 8,
+        "Type": "sh",
+    },
+    "ParameterURL": "http://www.sciencedirect.com/science/article/pii/S1053811911012092",
+    "ResponseFunction": {
+        "Coefficients": [
+            [600.2, 0.0, 0.0, 0.0, 0.0, 0.0],
+            [296.3, -115.2, 24.7, -4.4, -0.5, 1.8],
+            [199.8, -111.3, 41.8, -10.2, 2.1, -0.7],
+            [158.3, -98.7, 48.4, -17.1, 4.5, -1.4]
+        ],
+        "Type": "zsh"
+    }
+}
+```
+
+Contents of JSON file "`sub-01_model-csd_param-gm_dwimap.json`":
+
+```JSON
+{
+    "Model": {
+        "Description": "Multi-Shell Multi-Tissue (MSMT) Constrained Spherical Deconvolution (CSD)",
+        "URL": "https://mrtrix.readthedocs.io/en/latest/constrained_spherical_deconvolution/multi_shell_multi_tissue_csd.html",
+    },
+    "Description": "Gray matter",
+    "NonNegativity": "constrained",
+    "OrientationEncoding": {
+        "EncodingAxis": 3,
+        "Reference": "xyz",
+        "SphericalHarmonicBasis": "MRtrix3",
+        "SphericalHarmonicDegree": 0,
+        "Type": "sh",
+    },
+    "ResponseFunction": {
+        "Coefficients": [
+            [1041.0],
+            [436.6],
+            [224.9],
+            [128.8]
+        ],
+        "Type": "zsh"
+    }
+}
+```
+
+Contents of JSON file "`sub-01_model-csd_param-csf_dwimap.json`":
+
+```JSON
+{
+    "Model": {
+        "Description": "Multi-Shell Multi-Tissue (MSMT) Constrained Spherical Deconvolution (CSD)",
+        "URL": "https://mrtrix.readthedocs.io/en/latest/constrained_spherical_deconvolution/multi_shell_multi_tissue_csd.html",
+    },
+    "Description": "Cerebro-spinal fluid",
+    "NonNegativity": "constrained",
+    "OrientationEncoding": {
+        "EncodingAxis": 3,
+        "Reference": "xyz",
+        "SphericalHarmonicBasis": "MRtrix3",
+        "SphericalHarmonicDegree": 0,
+        "Type": "sh"
+    },
+    "ResponseFunction": {
+        "Coefficients": [
+            [3544.90770181],
+            [134.441453035],
+            [32.0826839826],
+            [29.3674604452]
+        ],
+        "Type": "zsh"
+    }
+}
+```
+
+Notes:
+
+-   In this example,
+    the gray matter and CSF compartments are specified in the spherical harmonics basis
+    with maximal spherical harmonic degrees of zero,
+    even though each image only contains a single volume
+    and could therefore be interpreted as simply scalar parameters.
+    This is recommended in this instance
+    given that the spherical harmonic basis imposes a $\sqrt(4\pi)$ scaling
+    that should be taken into account if comparing the values of these parameters
+    with the *l*=0 term of the white matter ODF.
+
+-   The response functions for GM and CSF have a maximal zonal spherical harmonic degree of zero,
+    such that only one coefficient is required for each unique *b*-value shell.
+    It is however nevertheless vital that these data be provided as a list of lists of floats,
+    where the length of each list is one;
+    storing these values as a list of floats would be erroneously interpreted
+    as coefficients of different zonal spherical harmonic degrees for a single *b*-value shell.
+
+#### A Neurite Orientation and Dispersion Imaging (NODDI) fit
+
+A fit of the model using the AMICO software.
+
+{{ MACROS___make_filetree_example(
+    {
+        "noddi_pipeline": {
+            "sub-01": {
+                "dwi": {
+                    "sub-01_model-noddi_param-direction_dwimap.nii.gz": "",
+                    "sub-01_model-noddi_param-direction_dwimap.json": "",
+                    "sub-01_model-noddi_param-odi_dwimap.nii.gz": "",
+                    "sub-01_model-noddi_param-odi_dwimap.json": "",
+                    "sub-01_model-noddi_param-icvf_dwimap.nii.gz": "",
+                    "sub-01_model-noddi_param-icvf_dwimap.json": "",
+                },
+            },
+        },
+    }
+) }}
+
+Dimensions of NIfTI image "`sub-01_model-noddi_param-direction_dwimap.nii.gz`": *I*x*J*x*K*3 ([unit vector](#encoding-3vector))
+
+Dimensions of NIfTI image "`sub-01_model-noddi_param-odi_dwimap.nii.gz`": *I*x*J*x*K*1 ([scalar](#encoding-scalar))
+
+Dimensions of NIfTI image "`sub-01_model-noddi_param-icvf_dwimap.nii.gz`": *I*x*J*x*K*1 ([scalar](#encoding-scalar))
+
+Contents of JSON file "`sub-01_model-noddi_param-direction_dwimap.json`":
+
+```JSON
+{
+    "Model": {
+        "Description": "Neurite Orientation Dispersion and Density Imaging (NODDI)",
+        "URL": "https://www.sciencedirect.com/science/article/pii/S1053811914008519",
+        "Parameters": {
+            "ParallelDiffusivity": 0.0017,
+            "IsotropicDiffusivity": 0.003
+            },
+    },
+    "Description": "Direction",
+    "OrientationEncoding": {
+        "EncodingAxis": 3,
+        "Type": "unit3vector",
+        "Reference": "xyz",
+    },
+}
+```
+
+Contents of JSON file "`sub-01_model-noddi_param-odi_dwimap.json`":
+
+```JSON
+{
+    "Model": {
+        "Description": "Neurite Orientation Dispersion and Density Imaging (NODDI)",
+        "URL": "https://www.sciencedirect.com/science/article/pii/S1053811914008519",
+        "Parameters": {
+            "ParallelDiffusivity": 0.0017,
+            "IsotropicDiffusivity": 0.003
+            },
+    },
+    "Description": "Orientation dispersion index",
+    "ParameterURL": "https://doi.org/10.1016/j.neuroimage.2012.03.072"
+}
+```
+
+Contents of JSON file "`sub-01_model-noddi_param-icvf_dwimap.json`":
+
+```JSON
+{
+    "Model": {
+        "Description": "Neurite Orientation Dispersion and Density Imaging (NODDI)",
+        "URL": "https://www.sciencedirect.com/science/article/pii/S1053811914008519",
+        "Parameters": {
+            "ParallelDiffusivity": 0.0017,
+            "IsotropicDiffusivity": 0.003
+            },
+        },
+    "Description": "Intra-cellular volume fraction CVF",
+    "ParameterURL": "https://doi.org/10.1016/j.neuroimage.2012.03.072"
+}
+```
+
+#### An FSL `bedpostx` Ball-And-Sticks fit
+
+This example includes both bootstrap realizations of the model fit,
+and the aggregated means of those parameters across realizations.
+
+<!-- This block generates a file tree.
+A guide for using macros can be found at
+ https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
+-->
+{{ MACROS___make_filetree_example(
+    {
+        "bedpostx_pipeline": {
+            "sub-01": {
+                "dwi": {
+                    "sub-01_model-bs_desc-mean_param-s0_dwimap.nii.gz": "",
+                    "sub-01_model-bs_desc-mean_param-s0_dwimap.json": "",
+                    "sub-01_model-bs_desc-mean_param-polar_dwimap.nii.gz": "",
+                    "sub-01_model-bs_desc-mean_param-polar_dwimap.json": "",
+                    "sub-01_model-bs_desc-mean_param-vector_dwimap.nii.gz": "",
+                    "sub-01_model-bs_desc-mean_param-vector_dwimap.json": "",
+                    "sub-01_model-bs_desc-mean_param-vf_dwimap.nii.gz": "",
+                    "sub-01_model-bs_desc-mean_param-vf_dwimap.json": "",
+                    "sub-01_model-bs_desc-mean_param-vfsum_dwimap.nii.gz": "",
+                    "sub-01_model-bs_desc-mean_param-vfsum_dwimap.json": "",
+                    "sub-01_model-bs_desc-mean_param-diffusivity_dwimap.nii.gz": "",
+                    "sub-01_model-bs_desc-mean_param-diffusivity_dwimap.json": "",
+                    "sub-01_model-bs_desc-mean_param-dstd_dwimap.nii.gz": "",
+                    "sub-01_model-bs_desc-mean_param-dstd_dwimap.json": "",
+                    "sub-01_model-bs_desc-merged_param-polar_dwimap.nii.gz": "",
+                    "sub-01_model-bs_desc-merged_param-polar_dwimap.json": "",
+                    "sub-01_model-bs_desc-merged_param-vf_dwimap.nii.gz": "",
+                    "sub-01_model-bs_desc-merged_param-vf_dwimap.json": "",
+                },
+            },
+        },
+    }
+) }}
+
+Dimensions of NIfTI image "`sub-01_model-bs_desc-mean_param-s0_dwimap.nii.gz`": *I*x*J*x*K* ([scalar](#encoding-scalar))
+
+Dimensions of NIfTI image "`sub-01_model-bs_desc-mean_param-polar_dwimap.nii.gz`": *I*x*J*x*K*x(*2*x*N*) ([spherical coordinates](#encoding-spherical), orientations only; *N* orientations per voxel)
+
+Dimensions of NIfTI image "`sub-01_model-bs_desc-mean_param-vector_dwimap.nii.gz`": *I*x*J*x*K*x(*3*x*N*) ([3-vectors](#encoding-3vectors), unit norm; *N* orientations per voxel)
+
+Dimensions of NIfTI image "`sub-01_model-bs_desc-mean_param-vf_dwimap.nii.gz`": *I*x*J*x*K*x*N* ([scalar](#encoding-scalar); *N* values per voxel)
+
+Dimensions of NIfTI image "`sub-01_model-bs_desc-mean_param-vfsum_dwimap.nii.gz`": *I*x*J*x*K* ([scalar](#encoding-scalar))
+
+Dimensions of NIfTI image "`sub-01_model-bs_desc-mean_param-diffusivity_dwimap.nii.gz`": *I*x*J*x*K* ([scalar](#encoding-scalar))
+
+Dimensions of NIfTI image "`sub-01_model-bs_desc-mean_param-dstd_dwimap.nii.gz`": *I*x*J*x*K* ([scalar](#encoding-scalar))
+
+Dimensions of NIfTI image "`sub-01_model-bs_desc-merged_param-polar_dwimap.nii.gz`": *I*x*J*x*K*x(*2*x*N*)x*R* ([spherical coordinates](#encoding-spherical), orientations only; *N* orientations per voxel; *R* bootstrap realizations)
+
+Dimensions of NIfTI image "`sub-01_model-bs_desc-merged_param-vf_dwimap.nii.gz`": *I*x*J*x*K*x*N*x*R* ([scalar](#encoding-scalar); *N* values per voxel; *R* bootstrap realizations)
+
+Contents of JSON file "`sub-01_model-bs_desc-mean_param-s0_dwimap.json`":
+
+```JSON
+{
+    "Description": "Estimated signal intensity with no diffusion weighting, ie. S0; mean across bootstrap realizations",
+    "Model": {
+        "Description": "Ball-And-Sticks model using FSL bedpostx",
+        "URL": "https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FDT",
+        "Parameters": {
+            "ARDFudgeFactor": 1.0,
+            "Fibers": 3
+        },
+        "BootstrapParameters": {
+            "Burnin": 1000,
+            "Jumps": 1250,
+            "SampleEvery": 25
+        }
+    }
+}
+```
+
+Contents of JSON file "`sub-01_model-bs_desc-mean_param-polar_dwimap.json`":
+
+```JSON
+{
+    "Description": "Fibre orientations encoded using polar angles; mean across bootstrap realizations",
+    "Model": {
+        "Description": "Ball-And-Sticks model using FSL bedpostx",
+        "URL": "https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FDT",
+        "Parameters": {
+            "ARDFudgeFactor": 1.0,
+            "Fibers": 3
+        },
+        "BootstrapParameters": {
+            "Burnin": 1000,
+            "Jumps": 1250,
+            "SampleEvery": 25
+        }
+    },
+    "OrientationEncoding": {
+        "EncodingAxis": 3,
+        "Reference": "bvec",
+        "Type": "unitspherical"
+    }
+}
+```
+
+Contents of JSON file "`sub-01_model-bs_desc-mean_param-vector_dwimap.json`":
+
+```JSON
+{
+    "Description": "Fibre orientations encoded using 3-vectors; mean across bootstrap realizations",
+    "Model": {
+        "Description": "Ball-And-Sticks model using FSL bedpostx",
+        "URL": "https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FDT",
+        "Parameters": {
+            "ARDFudgeFactor": 1.0,
+            "Fibers": 3
+        },
+        "BootstrapParameters": {
+            "Burnin": 1000,
+            "Jumps": 1250,
+            "SampleEvery": 25
+        }
+    },
+    "OrientationEncoding": {
+        "EncodingAxis": 3,
+        "Reference": "bvec",
+        "Type": "unit3vector"
+    }
+}
+```
+
+Contents of JSON file "`sub-01_model-bs_desc-mean_param-vf_dwimap.json`":
+
+```JSON
+{
+    "Description": "Volume fractions of stick components; mean across bootstrap realizations",
+    "Model": {
+        "Description": "Ball-And-Sticks model using FSL bedpostx",
+        "URL": "https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FDT",
+        "Parameters": {
+            "ARDFudgeFactor": 1.0,
+            "Fibers": 3
+        },
+        "BootstrapParameters": {
+            "Burnin": 1000,
+            "Jumps": 1250,
+            "SampleEvery": 25
+        }
+    },
+    "OrientationEncoding": {
+        "Type": "scalar"
+    }
+}
+```
+
+Contents of JSON file "`sub-01_model-bs_desc-mean_param-vfsum_dwimap.json`":
+
+```JSON
+{
+    "Description": "Sum of volume fractions of stick components; mean across bootstrap realizations",
+    "Model": {
+        "Description": "Ball-And-Sticks model using FSL bedpostx",
+        "URL": "https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FDT",
+        "Parameters": {
+            "ARDFudgeFactor": 1.0,
+            "Fibers": 3
+        },
+        "BootstrapParameters": {
+            "Burnin": 1000,
+            "Jumps": 1250,
+            "SampleEvery": 25
+        }
+    }
+}
+```
+
+Contents of JSON file "`sub-01_model-bs_desc-mean_param-diffusivity_dwimap.json`":
+
+```JSON
+{
+    "Description": "Diffusivity; mean across bootstrap realizations",
+    "Model": {
+        "Description": "Ball-And-Sticks model using FSL bedpostx",
+        "URL": "https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FDT",
+        "Parameters": {
+            "ARDFudgeFactor": 1.0,
+            "Fibers": 3
+        },
+        "BootstrapParameters": {
+            "Burnin": 1000,
+            "Jumps": 1250,
+            "SampleEvery": 25
+        }
+    },
+    "Units": "mm^2/s"
+}
+```
+
+Contents of JSON file "`sub-01_model-bs_desc-mean_param-dstd_dwimap.json`":
+
+```JSON
+{
+    "Description": "Diffusivity variance parameter; mean across bootstrap realizations",
+    "Model": {
+        "Description": "Ball-And-Sticks model using FSL bedpostx",
+        "URL": "https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FDT",
+        "Parameters": {
+            "ARDFudgeFactor": 1.0,
+            "Fibers": 3
+        },
+        "BootstrapParameters": {
+            "Burnin": 1000,
+            "Jumps": 1250,
+            "SampleEvery": 25
+        }
+    },
+    "Units": "TODO"
+}
+```
+
+Contents of JSON file "`sub-01_model-bs_desc-merged_param-polar_dwimap.json`":
+
+```JSON
+{
+    "BootstrapAxis": 4,
+    "Description": "Fibre orientations encoded using polar angles; concatenated bootstrap realizations",
+    "Model": {
+        "Description": "Ball-And-Sticks model using FSL bedpostx",
+        "URL": "https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FDT",
+        "Parameters": {
+            "ARDFudgeFactor": 1.0,
+            "Fibers": 3
+        },
+        "BootstrapParameters": {
+            "Burnin": 1000,
+            "Jumps": 1250,
+            "SampleEvery": 25
+        }
+    },
+    "OrientationEncoding": {
+        "EncodingAxis": 3,
+        "ReferenceAxes": "bvec",
+        "Type": "unitspherical"
+    }
+}
+```
+
+Contents of JSON file "`sub-01_model-bs_desc-merged_param-vf_dwimap.json`":
+
+```JSON
+{
+    "BootstrapAxis": 4,
+    "Description": "Volume fractions of stick components; concatenated bootstrap realizations",
+    "Model": {
+        "Description": "Ball-And-Sticks model using FSL bedpostx",
+        "URL": "https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FDT",
+        "Parameters": {
+            "ARDFudgeFactor": 1.0,
+            "Fibers": 3
+        },
+        "BootstrapParameters": {
+            "Burnin": 1000,
+            "Jumps": 1250,
+            "SampleEvery": 25
+        }
+    },
+    "OrientationEncoding": {
+        "Type": "scalar"
+    }
+}
+```
+
+Notes:
+
+-   Here the descriptors "`merged`" and "`mean`" have been utilized
+    to distinguish between the comprehensive set of all bootstrap realizations
+    and the computed mean statistics of parameters across all realizations respectively,
+    as this is the terminology utilized by the FSL software itself.
+    These labels are not however a part of the specification.
+
+-   Care must be taken for images of greater than three dimensions
+    where additional dimensions do *not* encode anisotropy information:
+
+    -   In image `"*_param-vf_desc-mean*_*"`,
+        the fourth image axis encodes scalar information across stick components.
+        Since this is *not* coefficients in some orientation encoding,
+        but the image possesses more than three axes,
+        field `"OrientationEncoding"["Type"]` MUST be specified as `"scalar"`.
+
+    -   Image `"*_param-vfsum_*"`is a three-dimensional image,
+        and therefore the fact that it encodes a scalar parameter
+        can be robustly inferred without reference to metadata information.
+
+    -   In image `"sub-01_model-bs_desc-merged_param-vf_dwimap.json"`,
+        there are two extra image dimensions beyond the three spatial dimensions:
+        the fourth image axis encodes across the multiple stick components per voxel,
+        and the fifth axis encodes realizations across bootstraps.
+        it is therefore necessary to explicitly specify
+        that the parameter being encoded in the data,
+        being the volume fractions of individual stick components,
+        do not have any anisotropy,
+        and therefore field `"OrientationEncoding"["Type"]` MUST be specified as `"scalar"`.
+
+### Appendix
+
+#### Spherical Harmonics
+
+-   Concepts shared across all spherical harmonics bases:
+
+    -   Basis functions:
+
+        ![SH basis functions](https://latex.codecogs.com/gif.latex?Y_l^m(\theta,\phi)&space;=&space;\sqrt{\frac{(2l&plus;1)}{4\pi}\frac{(l-m)!}{(l&plus;m)!}}&space;P_l^m(\cos&space;\theta)&space;e^{im\phi}")
+
+        for integer *order* *l*, *phase* *m*, associated Legendre polynomials *P*.
+
+    -   (Truncated) basis coefficients:
+
+        ![SH basis coefficients](https://latex.codecogs.com/gif.latex?f(\theta,\phi)&space;=&space;\sum_{l=0}^{l_\text{max}}&space;\sum_{m=-l}^{l}&space;c_l^m&space;Y_l^m(\theta,\phi)")
+
+        for *maximum* spherical harmonic order *l<sub>max</sub>*.
+
+    -   Functions assumed to be real: conjugate symmetry is assumed, that is,
+        *Y*(*l*,-*m*) = *Y*(*l*,*m*)\*, where \* denotes the complex
+        conjugate.
+
+    -   Antipodally symmetric: all basis functions with odd degree are
+        assumed zero; `AntipodalSymmetry` MUST NOT be set to `False`.
+
+    -   Utilized basis functions:
+
+        -   `mrtrix3`
+
+        ![MRtrix3 SH basis functions](https://latex.codecogs.com/gif.latex?Y_{lm}(\theta,\phi)=\begin{Bmatrix}&space;0&\text{if&space;}l\text{&space;is&space;odd},\\&space;\sqrt{2}\times\text{Im}\left[Y_l^{-m}(\theta,\phi)\right]&\text{if&space;}m<0,\\&space;Y_l^0(\theta,\phi)&\text{if&space;}m=0,\\&space;\sqrt{2}\times\text{Re}\left[Y_l^m(\theta,\phi)\right]&\text{if&space;}m>0\\&space;\end{Bmatrix})
+
+        -   `descoteaux`
+
+        ![Descoteaux SH basis functions](https://latex.codecogs.com/gif.latex?Y_{lm}(\theta,\phi)=\begin{Bmatrix}&space;0&\text{if&space;}l\text{&space;is&space;odd},\\&space;\sqrt{2}\times\text{Re}\left[Y_l^{-m}(\theta,\phi)\right]&\text{if&space;}m<0,\\&space;Y_l^0(\theta,\phi)&\text{if&space;}m=0,\\&space;\sqrt{2}\times\text{Im}\left[Y_l^m(\theta,\phi)\right]&\text{if&space;}m>0\\&space;\end{Bmatrix})
+
+    -   Mapping between image volume *V* and spherical harmonic basis
+        function coefficient *Y<sub>l,m</sub>*:
+
+        *V<sub>l,m</sub>* = (*l*(*l*+1) / 2) + *m*
+
+        | ***V*** | **Coefficient**    |
+        | ------- | ------------------ |
+        | 0       | *Y<sub>0,0</sub>*  |
+        | 1       | *Y<sub>2,-2</sub>* |
+        | 2       | *Y<sub>2,-1</sub>* |
+        | 3       | *Y<sub>2,0</sub>*  |
+        | 4       | *Y<sub>2,1</sub>*  |
+        | 5       | *Y<sub>2,2</sub>*  |
+        | 6       | *Y<sub>4,-4</sub>* |
+        | 7       | *Y<sub>4,-3</sub>* |
+        | ...     | ...                |
+
+    -   Relationship between maximal spherical harmonic degree *l<sub>max</sub>*
+        and number of image volumes *N*:
+
+        *N* = ((*l<sub>max</sub>*+1) x (*l<sub>max</sub>*+2)) / 2
+
+        | ***l<sub>max</sub>*** | 0   | 2   | 4   | 6   | 8   | 10  | ...  |
+        | --------------------- | --- | --- | --- | --- | --- | --- | ---- |
+        | ***N***               | 1   | 6   | 15  | 28  | 45  | 66  | ...  |
+
+    -   Relationship between maximal degree of *zonal* spherical harmonic
+        function (spherical harmonics function where all *m* != 0 terms are
+        assumed to be zero; used for response function definition and similar) and
+        number of coefficients *N*:
+
+        *N* = 1 + (*l<sub>max</sub>* / 2)
+
+        | ***l<sub>max</sub>*** | 0   | 2   | 4   | 6   | 8   | 10  | ...  |
+        | --------------------- | --- | --- | --- | --- | --- | --- | ---- |
+        | ***N***               | 1   | 2   | 3   | 4   | 5   | 6   | ...  |
diff --git a/src/metaschema.json b/src/metaschema.json
index 49d0f8cab7..ec58fe60e6 100644
--- a/src/metaschema.json
+++ b/src/metaschema.json
@@ -419,9 +419,10 @@
             "^derivatives$": {
               "type": "object",
               "properties": {
-                "common_derivatives": { "$ref": "#/definitions/json" }
+                "common_derivatives": { "$ref": "#/definitions/json" },
+                "diffusion": { "$ref": "#/definitions/json" }
               },
-              "required": ["common_derivatives"],
+              "required": ["common_derivatives", "diffusion"],
               "additionalProperties": false
             },
             "^(?!derivatives$)[a-z_]+$": {
diff --git a/src/schema/objects/entities.yaml b/src/schema/objects/entities.yaml
index be94a5eb0a..bc51a9cd32 100644
--- a/src/schema/objects/entities.yaml
+++ b/src/schema/objects/entities.yaml
@@ -177,6 +177,13 @@ modality:
     For example, `sub-01_mod-T1w_defacemask.nii.gz`.
   type: string
   format: label
+model:
+  name: model
+  display_name: Model
+  description: |
+    The `model-<label>` entity can be used to distinguish different models.
+  type: string
+  format: label
 mtransfer:
   name: mt
   display_name: Magnetization Transfer
@@ -206,6 +213,13 @@ nucleus:
     the associated metadata.
   type: string
   format: label
+parameter:
+  name: param
+  display_name: Parameter
+  description: |
+    The `param-<label>` entity can be used to distinguish different parameters.
+  type: string
+  format: label
 part:
   name: part
   display_name: Part
diff --git a/src/schema/objects/enums.yaml b/src/schema/objects/enums.yaml
index 19e0e30307..c13bd1899f 100644
--- a/src/schema/objects/enums.yaml
+++ b/src/schema/objects/enums.yaml
@@ -1452,3 +1452,40 @@ microvascular:
   display_name: microvascular
   description: |
     The origin of a tissue: microvascular
+bvec:
+  value: bvec
+  display_name: bvec
+  description: |
+    The three spatial image axes; **unless** those axes form a right-handed coordinate system
+    (that is, the 3x3 linear component of the NIfTI header transformation has a positive determinant),
+    in which case the negative of the first axis orientation is the first reference.
+ijk:
+  value: ijk
+  display_name: ijk
+  description: |
+    The three spatial image axes define the orientation.
+xyz:
+  value: xyz
+  display_name: xyz
+  description: |
+    The 'real' / 'scanner' space axes, which are independent of the NIfTI image header transform,
+    define the orientation reference.
+eigen:
+  value: eigen
+  display_name: eigen
+  description: |
+    List of 4 floating-point values must be specified; these are interpreted as three ordered eigenvalues of a
+    rank 2 tensor, followed by a reference b=0 intensity.
+zsh:
+  value: zsh
+  display_name: zsh
+  description: |
+    Either of (1) a list of floating-point values:
+    Values correspond to the response function coefficient for each consecutive even zonal spherical harmonic
+    degree starting from zero;
+    OR (2) List of lists of floating-point values.
+    One list per unique b-value.
+    Each individual list contains a coefficient per even zonal spherical harmonic degree starting from zero.
+    If the response function utilized has a different number of non-zero zonal spherical harmonic coefficients
+    for different b-values,
+    these must be padded with zeroes such that all lists contain the same number of floating-point values.
diff --git a/src/schema/objects/metadata.yaml b/src/schema/objects/metadata.yaml
index e6567a57f5..413170c5e9 100644
--- a/src/schema/objects/metadata.yaml
+++ b/src/schema/objects/metadata.yaml
@@ -4197,3 +4197,279 @@ iEEGReference:
     this field should have a general description and the channel specific
     reference should be defined in the `channels.tsv` file.
   type: string
+Model:
+  name: Model
+  display_name: Model
+  description: |
+    Dictionary containing information about the model.
+  type: object
+  properties:
+    Description:
+      $ref: objects.metadata.Description
+    TermURL:
+      $ref: objects.metadata.TermURL
+    BootstrapParameters:
+      $ref: objects.metadata.BootstrapParameters__Model
+    Parameters:
+      $ref: objects.metadata.Parameters__Model
+BootstrapParameters__Model:
+  name: BootstrapParameters
+  display_name: Bootstrap Parameters
+  description: |
+    Parameters relating to the generation of multiple realizations of the model fit using bootstrapping.
+  type: object
+Parameters__Model:
+  name: Parameters
+  display_name: Model Parameters
+  description: |
+    Dictionary containing information about the parameters of the model.
+  type: object
+  properties:
+    FitMethod:
+      $ref: objects.metadata.FitMethod__ModelParameters
+    Iterations:
+      $ref: objects.metadata.Iterations__ModelParameters
+    OutlierRejectionMethod:
+      $ref: objects.metadata.OutlierRejectionMethod__ModelParameters
+    Samples:
+      $ref: objects.metadata.Samples__ModelParameters
+    IsotropicDiffusivity:
+      $ref: objects.metadata.IsotropicDiffusivity__ModelParameters
+    ParallelDiffusivity:
+      $ref: objects.metadata.ParallelDiffusivity__ModelParameters
+FitMethod__ModelParameters:
+  name: FitMethod
+  display_name: Fit Method
+  description: |
+    The optimization procedure used to fit the intrinsic model parameters to the empirical
+    diffusion-weighted signal.
+  type: string
+  enum:
+    - ols
+    - wls
+    - iwls
+    - nlls
+Iterations__ModelParameters:
+  name: Iterations
+  display_name: Iterations
+  description: |
+    The number of iterations used for any form of model fitting procedure where the number of iterations is a
+    fixed input parameter.
+  type: integer
+  minimum: 0
+OutlierRejectionMethod__ModelParameters:
+  name: OutlierRejectionMethod
+  display_name: Outlier Rejection Method
+  description: |
+    Text describing any form of rejection of outlier values that was performed during fitting of the model.
+  type: string
+Samples__ModelParameters:
+  name: Samples
+  display_name: Samples
+  description: |
+    The number of realizations of a diffusion model from which statistical summaries
+    (such as mean, standard deviation) of those parameters were computed.
+  type: integer
+  minimum: 0
+IsotropicDiffusivity__ModelParameters:
+  name: IsotropicDiffusivity
+  display_name: Isotropic Diffusivity
+  description: |
+    Diffusivity of an isotropic component (in units of mm^2/s).
+  type: number
+  unit: mm^2/s
+ParallelDiffusivity__ModelParameters:
+  name: ParallelDiffusivity
+  display_name: Parallel Diffusivity
+  description: |
+    Diffusivity of a axial/parallel component (in units of mm^2/s).
+  type: number
+  unit: mm^2/s
+BootstrapAxis:
+  name: BootstrapAxis
+  display_name: Bootstrap Axis
+  description: |
+    If multiple realizations of a given parameter are stored in a NIfTI image,
+    this field nominates the image axis (indexed from zero) along which those multiple realizations are stored.
+  type: integer
+  minimum: 0
+NonNegativity:
+  name: NonNegativity
+  display_name: Non-Negativity
+  description: |
+    Specifies whether, during model fitting, the parameter was regularized to not take extreme negative values, or was
+    explicitly forbidden from taking negative values.
+  type: string
+  enum:
+    - regularized
+    - constrained
+OrientationEncoding:
+  name: OrientationEncoding
+  display_name: Orientation Encoding
+  description: |
+    Dictionary containing information about the orientation encoding of the model.
+  type: object
+  required: [EncodingAxis, Reference, Type]
+  properties:
+    AmplitudesDirections:
+      $ref: objects.metadata.AmplitudesDirections__OrientationEncoding
+    AntipodalSymmetry:
+      $ref: objects.metadata.AntipodalSymmetry__OrientationEncoding
+    EncodingAxis:
+      $ref: objects.metadata.EncodingAxis__OrientationEncoding
+    FillValue:
+      $ref: objects.metadata.FillValue__OrientationEncoding
+    Reference:
+      $ref: objects.metadata.Reference__OrientationEncoding
+    SphericalHarmonicsBasis:
+      $ref: objects.metadata.SphericalHarmonicsBasis__OrientationEncoding
+    SphericalHarmonicsDegree:
+      $ref: objects.metadata.SphericalHarmonicsDegree__OrientationEncoding
+    TensorRank:
+      $ref: objects.metadata.TensorRank__OrientationEncoding
+    Type:
+      $ref: objects.metadata.Type__OrientationEncoding
+AmplitudesDirections__OrientationEncoding:
+  name: AmplitudesDirections
+  display_name: Amplitudes Directions
+  description: |
+    List of lists of floats. Data are either [spherical coordinates (directions only)](#encoding-spherical) or
+    [3-vectors](#encoding-3vector) with unit norm. Defines the dense directional basis set on which samples of a
+    spherical function within each voxel are provided. The length of the list must be equal to the number of
+    volumes in the image.
+
+    REQUIRED for "Type": "amplitudes"; MUST NOT be specified otherwise.
+  type: array
+  items:
+    type: array
+    items:
+      type: number
+AntipodalSymmetry__OrientationEncoding:
+  name: AntipodalSymmetry
+  display_name: Antipodal Symmetry
+  description: |
+    Boolean. Indicates whether orientation information should be interpreted as being antipodally symmetric.
+    Assumed to be True if omitted.
+  type: boolean
+EncodingAxis__OrientationEncoding:
+  name: EncodingAxis
+  display_name: Encoding Axis
+  description: |
+    Integer. Indicates the image axis (indexed from zero) along which image intensities should be interpreted as
+    corresponding to orientation encoding.
+  type: integer
+  minimum: 0
+FillValue__OrientationEncoding:
+  name: FillValue
+  display_name: Fill Value
+  description: |
+    Float. Value stored in image when the number of discrete orientations in a given voxel is fewer than the
+    maximal number for that image.
+  type: number
+Reference__OrientationEncoding:
+  name: Reference
+  display_name: Reference
+  description: |
+    The reference coordinate system for the orientation encoding.
+  type: string
+  enum:
+    - $ref: objects.enums.bvec.value
+    - $ref: objects.enums.ijk.value
+    - $ref: objects.enums.xyz.value
+SphericalHarmonicsBasis__OrientationEncoding:
+  name: SphericalHarmonicsBasis
+  display_name: Spherical Harmonics Basis
+  description: |
+    String. Options are: { `mrtrix3`, `descoteaux` }.
+    Details are provided in the [spherical harmonics bases](#spherical-harmonics-bases) section.
+  type: string
+  enum:
+    - mrtrix3
+    - descoteaux
+SphericalHarmonicsDegree__OrientationEncoding:
+  name: SphericalHarmonicsDegree
+  display_name: Spherical Harmonics Degree
+  description: |
+    Integer. The maximal spherical harmonic order *l<sub>max</sub>*;
+    the number of volumes in the associated NIfTI image must correspond to this value as per the relationship
+    described in the [spherical harmonics bases](#spherical-harmonics-bases) section.
+  type: integer
+  minimum: 0
+TensorRank__OrientationEncoding:
+  name: TensorRank
+  display_name: Tensor Rank
+  description: |
+    Integer. Rank of tensor reporesentation. Specification currently only supports a value of 2.
+
+    REQUIRED for `"Type": "tensor"; MUST NOT be specified otherwise.
+  type: integer
+  minimum: 0
+Type__OrientationEncoding:
+  name: Type
+  display_name: Type
+  description: |
+    Specifies the type of orientation information (if any) encoded in the NIfTI image.
+  type: string
+  enum:
+    - scalar
+    - dec
+    - unitspherical
+    - spherical
+    - unit3vector
+    - 3vector
+    - tensor
+    - sh
+    - amplitudes
+ParameterURL:
+  name: ParameterURL
+  display_name: Parameter URL
+  description: |
+    URL to documentation that describes the specific model parameter that is encoded within the data file.
+  type: string
+ResponseFunction:
+  name: ResponseFunction
+  display_name: Response Function
+  description: |
+    Dictionary containing information about the response function used to fit the model.
+  type: object
+  required: [Coefficients, Type]
+  properties:
+    Coefficients:
+      $ref: objects.metadata.Coefficients__ResponseFunction
+    Type:
+      $ref: objects.metadata.Type__ResponseFunction
+Coefficients__ResponseFunction:
+  name: Coefficients
+  display_name: Coefficients
+  description: |
+    The coefficients of the response function.
+    Either a list of floats, or a list of lists of floats,
+    depending on the mathematical form of the response function and possibly the data to which it applies;
+    see further below.
+  type: array
+  items:
+    anyOf:
+      - type: array
+        items:
+          type: number
+      - type: number
+Type__ResponseFunction:
+  name: Type
+  display_name: Response Function Type
+  description: |
+    The mathematical form in which the response function coefficients are provided; see further below.
+    Levels are "eigen" (list of 4 floating-point values must be specified;
+    these are interpreted as three ordered eigenvalues of a rank 2 tensor, followed by a reference b=0 intensity.)
+    and "zsh" (Either of (1) a list of floating-point values:
+    Values correspond to the response function coefficient for each consecutive even zonal spherical harmonic
+    degree starting from zero;
+    OR (2) List of lists of floating-point values.
+    One list per unique b-value.
+    Each individual list contains a coefficient per even zonal spherical harmonic degree starting from zero.
+    If the response function utilized has a different number of non-zero zonal spherical harmonic coefficients for
+    different b-values,
+    these must be padded with zeroes such that all lists contain the same number of floating-point values.)
+  type: string
+  enum:
+    - $ref: objects.enums.eigen.value
+    - $ref: objects.enums.zsh.value
diff --git a/src/schema/objects/suffixes.yaml b/src/schema/objects/suffixes.yaml
index 1e2825ced2..578378668e 100644
--- a/src/schema/objects/suffixes.yaml
+++ b/src/schema/objects/suffixes.yaml
@@ -602,6 +602,12 @@ dwi:
   display_name: Diffusion-weighted image
   description: |
     Diffusion-weighted imaging contrast (specialized T2 weighting).
+dwimap:
+  value: dwimap
+  display_name: Diffusion-weighted derivative image
+  description: |
+    Diffusion-weighted derivative image.
+    This suffix is used to indicate that the image is a derivative of a diffusion-weighted image.
 eeg:
   value: eeg
   display_name: Electroencephalography
diff --git a/src/schema/rules/checks/deprecations.yml b/src/schema/rules/checks/deprecations.yml
index d7a3c27372..d45be8356a 100644
--- a/src/schema/rules/checks/deprecations.yml
+++ b/src/schema/rules/checks/deprecations.yml
@@ -1,3 +1,4 @@
+---
 AnatomicalLandmarkCoordinateSystemDeprecation:
   issue:
     code: ELEKTA_NEUROMAG_DEPRECATED
diff --git a/src/schema/rules/entities.yaml b/src/schema/rules/entities.yaml
index 44174d333e..9a38167f4d 100644
--- a/src/schema/rules/entities.yaml
+++ b/src/schema/rules/entities.yaml
@@ -24,6 +24,8 @@
 - processing
 - hemisphere
 - space
+- model
+- parameter
 - split
 - recording
 - chunk
diff --git a/src/schema/rules/files/deriv/imaging.yaml b/src/schema/rules/files/deriv/imaging.yaml
index d2ce8a451d..5f4bf1d872 100644
--- a/src/schema/rules/files/deriv/imaging.yaml
+++ b/src/schema/rules/files/deriv/imaging.yaml
@@ -121,6 +121,20 @@ dwi_scannerderivatives:
       - meta.templates.deriv.volumetric.entities
       - rules.files.raw.dwi.ScannerDerivatives.entities
 
+dwimap_volumetric:
+  $ref:
+    - meta.templates.deriv.volumetric
+  datatypes:
+    - dwi
+  entities:
+    $ref:
+      - meta.templates.deriv.volumetric.entities
+      - rules.files.raw.dwi.dwi.entities
+    model: required
+    parameter: required
+  suffixes:
+    - dwimap
+
 func_volumetric:
   $ref:
     - meta.templates.deriv.volumetric
diff --git a/src/schema/rules/sidecars/derivatives/diffusion.yaml b/src/schema/rules/sidecars/derivatives/diffusion.yaml
new file mode 100644
index 0000000000..2851216646
--- /dev/null
+++ b/src/schema/rules/sidecars/derivatives/diffusion.yaml
@@ -0,0 +1,46 @@
+---
+OrientationEncodingTypeAmplitudes:
+  selectors:
+    - dataset.dataset_description.DatasetType == "derivative"
+    - suffix == "dwimap"
+    - sidecar.OrientationEncoding.Type == "amplitudes"
+  fields:
+    AmplitudesDirections__OrientationEncoding:
+      level: required
+      level_addendum: if `OrientationEncoding.Type` is `"amplitudes"`
+
+OrientationEncodingTypeSphericalHarmonics:
+  selectors:
+    - dataset.dataset_description.DatasetType == "derivative"
+    - suffix == "dwimap"
+    - sidecar.OrientationEncoding.Type == "sh"
+  fields:
+    SphericalHarmonicsBasis__OrientationEncoding:
+      level: required
+      level_addendum: if `OrientationEncoding.Type` is `"sh"`
+    SphericalHarmonicsDegree__OrientationEncoding:
+      level: optional
+      level_addendum: if `OrientationEncoding.Type` is `"sh"`
+
+OrientationEncodingTypeTensor:
+  selectors:
+    - dataset.dataset_description.DatasetType == "derivative"
+    - suffix == "dwimap"
+    - sidecar.OrientationEncoding.Type == "tensor"
+  fields:
+    TensorRank__OrientationEncoding:
+      level: required
+      level_addendum: if `OrientationEncoding.Type` is `"tensor"`
+
+OrientationEncodingTypeNotScalar:
+  selectors:
+    - dataset.dataset_description.DatasetType == "derivative"
+    - suffix == "dwimap"
+    - sidecar.OrientationEncoding.Type != "scalar"
+  fields:
+    EncodingAxis__OrientationEncoding:
+      level: required
+      level_addendum: if `OrientationEncoding.Type` is not `"scalar"`
+    Reference__OrientationEncoding:
+      level: required
+      level_addendum: if `OrientationEncoding.Type` is not `"scalar"`
diff --git a/tools/schemacode/src/bidsschematools/render/text.py b/tools/schemacode/src/bidsschematools/render/text.py
index 34bce386ac..97da22af92 100644
--- a/tools/schemacode/src/bidsschematools/render/text.py
+++ b/tools/schemacode/src/bidsschematools/render/text.py
@@ -177,6 +177,10 @@ def make_glossary(schema, src_path=None):
         ]
         levels = list(obj_def.get("enum", []) or obj_def.get("definition", {}).get("Levels", {}))
         if levels:
+            for level in levels:
+                if isinstance(level, dict) and not hasattr(level, "name"):
+                    raise ValueError(f"level {level} has no name")
+
             levels = [level["name"] if isinstance(level, dict) else level for level in levels]
             text += f"**Allowed values**: `{'`, `'.join(levels)}`\n\n"
 
@@ -326,6 +330,10 @@ def make_filename_template(
     file_rules = schema.rules.files[dstype]
     file_groups = {}
     for rule in file_rules.values(level=2):
+        if not hasattr(rule, "datatypes"):
+            # Just ignore any rules that do not have a datatypes field
+            continue
+
         for datatype in rule.datatypes:
             file_groups.setdefault(datatype, []).append(rule)