From 1eed55f3915d16f8838c42da5eff7be73418fbc6 Mon Sep 17 00:00:00 2001
From: Charles Tapley Hoyt <cthoyt@gmail.com>
Date: Tue, 4 Feb 2025 17:45:27 +0100
Subject: Add CRediT roles to JATS

Enable annotating author roles using the Contribution Role Taxonomy
(CRediT) and export this information in conformant JATS

Closes #10152.

Co-Authored-By: Jez Cope <457628+jezcope@users.noreply.github.com>
---
 doc/jats.md | 81 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 81 insertions(+)

(limited to 'doc')

diff --git a/doc/jats.md b/doc/jats.md
index 4ac54f25b..a723ccce5 100644
--- a/doc/jats.md
+++ b/doc/jats.md
@@ -61,6 +61,85 @@ Metadata Values
         set it used, as affiliation links are not allowed in that
         schema.
 
+    `roles`
+    :   a list of dictionaries describing the author's role(s).
+        Each role is added as an [`<role>`] element to
+        the author's [`<contrib>`] element. The following examples
+        illustrate:
+
+        An ad-hoc role:
+
+        ```yaml
+        roles:
+          - name: Dolphin Catcher
+        ```
+
+        A role specified with CRediT.
+
+        ```yaml
+        roles:
+          - credit: writing-review-editing
+        ```
+
+        The `credit-name` is automatically looked up from
+        the CRediT taxonomy, but you can also specify it
+        yourself:
+
+        ```yaml
+        roles:
+          - credit: writing-review-editing
+            credit-name: Writing – review & editing
+        ```
+
+        A role specified with CRediT, including an
+        optional degree of contribution. Note that
+        specifying the degree only is allowed when
+        using CRediT roles and not ad-hoc roles.
+
+        ```yaml
+        roles:
+          - credit: writing-review-editing
+            degree: Lead
+        ```
+
+        A role specified with CRediT with a label override,
+        useful for internationalization:
+
+        ```yaml
+        roles:
+          - credit: writing-review-editing
+            name: Escrita – revisão e edição
+        ```
+
+        The value for `credit` and `credit-name`
+        must be from one of the 14 terms from the
+        Contribution Role Taxonomy (CRediT):
+
+        | `credit`                 | `credit-name`              |
+        |--------------------------|----------------------------|
+        | `conceptualization`      | Conceptualization          |
+        | `data-curation`          | Data curation              |
+        | `formal-analysis`        | Formal analysis            |
+        | `funding-acquisition`    | Funding acquisition        |
+        | `investigation`          | Investigation              |
+        | `methodology`            | Methodology                |
+        | `project-administration` | Project administration     |
+        | `resources`              | Resources                  |
+        | `software`               | Software                   |
+        | `supervision`            | Supervision                |
+        | `validation`             | Validation                 |
+        | `visualization`          | Visualization              |
+        | `writing-original-draft` | Writing – original draft   |
+        | `writing-review-editing` | Writing – review & editing |
+
+        JATS suggests in [`<degree-contribution>`] to use one of
+        the following three values when specifying the degree of
+        contribution:
+
+        1. `Lead`
+        2. `Equal`
+        3. `Supporting`
+
     `equal-contrib`
     :   boolean attribute used to mark authors who contributed
         equally to the work. The
@@ -483,3 +562,5 @@ Required metadata values:
 [`<institution-wrap>`]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/institution-wrap.html
 [`<institution>`]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/institution.html
 [`<pub-date>`]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/pub-date.html
+[`<role>`]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/role.html
+[`<degree-contribution>`]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/attribute/degree-contribution.html
-- 
cgit v1.2.3