Merge pull request #1525 from effigies/enh/citation_cff

[ENH] Permit CITATION.cff as structured alternative to some dataset_description fields

src/modality-agnostic-files.md

@@ -167,6 +167,26 @@ A guide for using macros can be found at
 -->
 {{ MACROS___render_text("objects.files.README.description") }}
 
+### `CITATION.cff`
+
+<!-- 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___render_text("objects.files.CITATION.description") }}
+
+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`
 
 <!-- This block generates a description.

src/schema/objects/files.yaml

@@ -12,6 +12,14 @@ CHANGES:
     [CPAN Changelog convention](https://metacpan.org/pod/release/HAARG/CPAN-Changes-0.400002/lib/\
     CPAN/Changes/Spec.pod).
     The `CHANGES` file MUST be either in ASCII or UTF-8 encoding.
+CITATION:
+  display_name: CITATION.cff
+  file_type: regular
+  description: |
+    A description of the citation information for the dataset, following the
+    [Citation File Format](https://citation-file-format.github.io/) specification.
+    This file permits more detailed and structured descriptions than
+    [dataset_description.json](SPEC_ROOT/glossary.md#dataset_description-files).
 LICENSE:
   display_name: License
   file_type: regular

src/schema/rules/checks/dataset.yaml

@@ -62,3 +62,30 @@ UnknownVersion:
     - path == 'dataset_description.json'
   checks:
     - intersects([json.BIDSVersion], schema.meta.versions)
+
+SingleSourceAuthors:
+  issue:
+    code: AUTHORS_AND_CITATION_FILE_MUTUALLY_EXCLUSIVE
+    level: error
+    message: |
+      CITATION.cff file found. The "Authors" field of dataset_description.json
+      must be removed to avoid inconsistency.
+  selectors:
+    - path == 'CITATION.cff'
+  checks:
+    - '!("Authors" in dataset.dataset_description)'
+
+SingleSourceCitationFields:
+  issue:
+    code: SINGLE_SOURCE_CITATION_FIELDS
+    level: warning
+    message: |
+      CITATION.cff file found. The "HowToAckowledge", "License",
+      and "ReferencesAndLinks" fields of dataset_description.json
+      should be removed to avoid inconsistency.
+  selectors:
+    - path == 'CITATION.cff'
+  checks:
+    - '!("HowToAcknowledge" in dataset.dataset_description)'
+    - '!("License" in dataset.dataset_description)'
+    - '!("ReferencesAndLinks" in dataset.dataset_description)'

src/schema/rules/files/common/core.yaml

@@ -5,6 +5,9 @@
 dataset_description:
   level: required
   path: dataset_description.json
+CITATION:
+  level: optional
+  path: CITATION.cff
 README:
   level: recommended
   stem: README