Skip to content

Dataset description

Templates:

  • dataset_description.json
  • README[.md|.rst|.txt]
  • CITATION.cff
  • CHANGES
  • LICENSE[.md|.rst|.txt]

dataset_description.json

The file dataset_description.json is a JSON file describing the dataset.

Every dataset MUST include this file with the following fields:

Key name Requirement Level Data type Description
Name REQUIRED string Name of the dataset.
BIDSVersion REQUIRED string The version of the BIDS standard that was used.
HEDVersion RECOMMENDED string or array of strings If HED tags are used: The version of the HED schema used to validate HED tags for study. May include a single schema or a base schema and one or more library schema.
DatasetLinks REQUIRED if BIDS URIs are used object of strings Used to map a given <dataset-name> from a BIDS URI of the form bids:<dataset-name>:path/within/dataset to a local or remote location. The <dataset-name>: "" (an empty string) is a reserved keyword that MUST NOT be a key in DatasetLinks (example: bids::path/within/dataset).
DatasetType RECOMMENDED string The interpretation of the dataset. For backwards compatibility, the default value is "raw".

Must be one of: "raw", "derivative".
License RECOMMENDED string The license for the dataset. The use of license name abbreviations is RECOMMENDED for specifying a license (see Licenses). The corresponding full license text MAY be specified in an additional LICENSE file.
Authors RECOMMENDED if CITATION.cff is not present array of strings List of individuals who contributed to the creation/curation of the dataset.
Keywords OPTIONAL array of strings A list of keywords that describe the content or subject matter of the dataset. These may be used to enhance the findability of the dataset on public archives.
Acknowledgements OPTIONAL string Text acknowledging contributions of individuals or institutions beyond those listed in Authors or Funding.
HowToAcknowledge OPTIONAL string Text containing instructions on how researchers using this dataset should acknowledge the original authors. This field can also be used to define a publication that should be cited in publications that use the dataset.
Funding OPTIONAL array of strings List of sources of funding (grant numbers).
EthicsApprovals OPTIONAL array of strings List of ethics committee approvals of the research protocols and/or protocol identifiers.
ReferencesAndLinks OPTIONAL array of strings List of references to publications that contain information on the dataset. A reference may be textual or a URI.
DatasetDOI OPTIONAL string The Digital Object Identifier of the dataset (not the corresponding paper). DOIs SHOULD be expressed as a valid URI; bare DOIs such as 10.0.2.3/dfjj.10 are DEPRECATED.
GeneratedBy RECOMMENDED array of objects Used to specify provenance of the dataset.
SourceDatasets RECOMMENDED array of objects Used to specify the locations and relevant attributes of all source datasets. Valid keys in each object include "URL", "DOI" (see URI), and "Version" with string values.

Each object in the GeneratedBy array includes the following REQUIRED, RECOMMENDED and OPTIONAL keys:

Key name Requirement Level Data type Description
Name REQUIRED string Name of the pipeline or process that generated the outputs. Use "Manual" to indicate the derivatives were generated by hand, or adjusted manually after an initial run of an automated pipeline.
Version RECOMMENDED string Version of the pipeline
Description OPTIONAL string Plain-text description of the pipeline or process that generated the outputs. RECOMMENDED if Name is "Manual".
CodeURL OPTIONAL string URL where the code used to generate the dataset may be found.
Container OPTIONAL object Used to specify the location and relevant attributes of software container image used to produce the dataset. Valid keys in this object include Type, Tag and [URI][uri] with [string][] values.

Example:

{
  "Name": "The mother of all experiments",
  "BIDSVersion": "1.6.0",
  "DatasetType": "raw",
  "License": "CC0",
  "Authors": [
    "Paul Broca",
    "Carl Wernicke"
  ],
  "Keywords": [
    "neuroscience",
    "language",
    "brain"
  ],
  "Acknowledgements": "Special thanks to Korbinian Brodmann for help in formatting this dataset in BIDS. We thank Alan Lloyd Hodgkin and Andrew Huxley for helpful comments and discussions about the experiment and manuscript; Hermann Ludwig Helmholtz for administrative support; and Claudius Galenus for providing data for the medial-to-lateral index analysis.",
  "HowToAcknowledge": "Please cite this paper: https://www.ncbi.nlm.nih.gov/pubmed/001012092119281",
  "Funding": [
    "National Institute of Neuroscience Grant F378236MFH1",
    "National Institute of Neuroscience Grant 5RMZ0023106"
  ],
  "EthicsApprovals": [
    "Army Human Research Protections Office (Protocol ARL-20098-10051, ARL 12-040, and ARL 12-041)"
  ],
  "ReferencesAndLinks": [
    "https://www.ncbi.nlm.nih.gov/pubmed/001012092119281",
    "Alzheimer A., & Kraepelin, E. (2015). Neural correlates of presenile dementia in humans. Journal of Neuroscientific Data, 2, 234001. doi:1920.8/jndata.2015.7"
  ],
  "DatasetDOI": "doi:10.0.2.3/dfjj.10",
  "HEDVersion": "8.0.0",
  "GeneratedBy": [
    {
      "Name": "reproin",
      "Version": "0.6.0",
      "Container": {
        "Type": "docker",
        "Tag": "repronim/reproin:0.6.0"
      }
    }
  ],
  "SourceDatasets": [
    {
      "URL": "s3://dicoms/studies/correlates",
      "Version": "April 11 2011"
    }
  ]
}

Derived dataset and pipeline description

As for any BIDS dataset, a dataset_description.json file MUST be found at the top level of every derived dataset: <dataset>/derivatives/<pipeline_name>/dataset_description.json.

In contrast to raw BIDS datasets, derived BIDS datasets MUST include a GeneratedBy key:

Key name Requirement Level Data type Description
GeneratedBy REQUIRED array of objects Used to specify provenance of the dataset.

If a derived dataset is stored as a subdirectory of the raw dataset, then the Name field of the first GeneratedBy object MUST be a substring of the derived dataset directory name. That is, in a directory <dataset>/derivatives/<pipeline>[-<variant>]/, the first GeneratedBy object should have a Name of <pipeline>.

Example:

{
  "Name": "FMRIPREP Outputs",
  "BIDSVersion": "1.6.0",
  "DatasetType": "derivative",
  "GeneratedBy": [
    {
      "Name": "fmriprep",
      "Version": "1.4.1",
      "Container": {
        "Type": "docker",
        "Tag": "poldracklab/fmriprep:1.4.1"
        }
    },
    {
      "Name": "Manual",
      "Description": "Re-added RepetitionTime metadata to bold.json files"
    }
  ],
  "SourceDatasets": [
    {
      "DOI": "doi:10.18112/openneuro.ds000114.v1.0.1",
      "URL": "https://openneuro.org/datasets/ds000114/versions/1.0.1",
      "Version": "1.0.1"
    }
  ]
}

README

A REQUIRED text file, README, SHOULD describe the dataset in more detail. The README file MUST be either in ASCII or UTF-8 encoding and MAY have one of the extensions: .md (Markdown), .rst (reStructuredText), or .txt. A BIDS dataset MUST NOT contain more than one README file (with or without extension) at its root directory. BIDS does not make any recommendations with regards to the Markdown flavor and does not validate the syntax of Markdown and reStructuredText. The README file SHOULD be structured such that its contents can be easily understood even if the used format is not rendered. A guideline for creating a good README file can be found in the bids-starter-kit.

CITATION.cff

A description of the citation information for the dataset, following the Citation File Format specification. This file permits more detailed and structured descriptions than dataset_description.json.

For most redundant fields between CITATION.cff and dataset_description.json, the CITATION.cff SHOULD take precedence. To avoid inconsistency, metadata present in CITATION.cff SHOULD NOT be be included in dataset_description.json, with the exception of Name and DatasetDOI, to ensure that CITATION.cff-unaware tools can generate references to the dataset. In particular, if CITATION.cff is present, the "Authors" field of dataset_description.json MUST be omitted, and the "HowToAcknowledge", "License" and "ReferencesAndLinks" SHOULD be omitted in favor of the CITATION.cff fields message/preferred-citation, license and references.

CHANGES

Version history of the dataset (describing changes, updates and corrections) MAY be provided in the form of a CHANGES text file. This file MUST follow the CPAN Changelog convention. The CHANGES file MUST be either in ASCII or UTF-8 encoding.

Example:

1.0.1 2015-08-27
  - Fixed slice timing information.

1.0.0 2015-08-17
  - Initial release.

LICENSE

A LICENSE file MAY be provided in addition to the short specification of the used license in the dataset_description.json "License" field. The "License" field and LICENSE file MUST correspond. The LICENSE file MUST be either in ASCII or UTF-8 encoding and MAY have one of the extensions: .md (Markdown), .rst (reStructuredText), or .txt.