Authors & Affiliations

Overview

An important goal for Quarto is to make it possible to use the same source document to produce multiple output formats. One significant challenge to overcome is defining a consistent way to express author and affiliation metadata such that articles targeting multiple Journals do not require special tweaking of authors and affiliations for each publication.

Quarto’s answer to this challenge is two-fold:

Parse a variety of expressions of authors and affiliations into a standard schema.
Provide de-normalized views of authors together with affiliations such that it is straightforward for template authors to create the LaTeX required by Journals.

Below we’ll explore these facilities in more detail from the standpoint of template authors. To learn more about these facilities from the perspective of article writers, see Authors & Affiliations.

Note

Note that while there is a great deal of variety afforded in how authors and affiliations are specified, for a given Journal template.qmd you will likely have a preferred approach, and it’s good form to seed the template with an example of this approach.

Author Metadata

Quarto will look in the author or authors field for data that can be parsed into a normalized representation of authors. This can be as simple as a name of list of names:

author:   
  - Norah Jones   
  - Bill Gates

Or alternatively can be a complex data structure expressing a variety of properties and attributes of authors along with their affiliations:

author:
  - name: Bill Gates
    orcid: 0000-0003-1689-0557
    email: bill@gates.com
    affiliations:
      - name: Bill & Melinda Gates Foundation
        address: 440 5th Ave N
        city: Seattle
        state: WA
        postal-code: 98109-4631

For both of the above expressions, Quarto processes and normalizes the author and affiliation data into the keys described below.

author

The author metadata key receives a simple list of names that will render properly in most existing Pandoc templates not aware of the Quarto extended schema.

authors

The authors metadata key contains the normalized author data structure. Affiliations are referenced (rather than placed inline), so this typically shouldn’t be used by templates to output author data. The order the authors appear in the metadata will be preserved.

affiliations

The affiliations metadata key contains the normalized affiliation data structure. Ids are automatically assigned if not defined. Affiliations contain no reference to their authors, so are typically not used by templates to output affiliation data. The order the affiliations appear in the metadata will be preserved. Duplicate affiliations are removed.

by-author

The by-author metadata key contains a denormalized version of the author data organized in the original order of the authors. Rather than referencing affiliations, each author will have the full parsed contents of affiliations available in the affiliations subkey, making it easy for template authors to iterate through authors and then, within that, their affiliations. The order the authors appear in the metadata will be preserved.

by-affiliation

The by-affiliation metadata key contains a denormalized version of affiliation data in the original order the affiliations appeared. Author data appears in order in the authors subkey, which contains the full parsed author data. This makes it easy for template authors to iterate over affiliations and the authors for each affiliation. The order the affiliations appear in the metadata will be preserved.

Author Schema

The complete, normalized, author schema is as follows:

author:
  - id: string
    number: number
    name:
      given: string
      family: string
      literal: string
      dropping-particle: string
      non-dropping-particle: string
    url: string
    email: string
    phone: string
    fax: string
    degrees: 
      # see schema below
    orcid: string
    note: string
    acknowledgements: string
    attributes:
      corresponding: boolean
      equal-contributor: boolean
      deceased: boolean
    roles: 
      # see schema below
    metadata: object
    affiliations: 
      # see schema below

Names

Most often, users will write a single string for name, like:

author: Norah Jones

or perhaps like:

author:
  - name: Norah Jones

Which will be parsed into:

author:
  - name:
      given: Norah
      family: Jones
      literal: Norah Jones

Quarto will parse names using BibTeX (a la openjournals/inara), supporting BibTeX’s parsing behavior for comma count, capitalization, and so on. When the name is unparseable by BibTeX, Quarto will attempt to parse names into given and family using spaces (everything after the last space is considered a family name), but to disambiguate, you may provide separate keys for the given name, family name and particle:

name:
  given: Norah
  family: Jones
  dropping-particle: von

Degrees

Degrees or academic titles can specified with degrees and can be either of:

A single string:
```
author: 
  degrees: PhD
```

An array of strings:

author: 
  degrees:
    - PhD
    - MsSc

It will always be normalized into an array of degrees.

Attributes

Recognized attribute keys that appear at the top level (for example, corresponding) will automatically be normalized under attributes. For example:

author:
  name: Norah Jones
  corresponding: true

would be normalized into:

author:
  - name:
      given: Norah
      family: Jones
      literal: Norah Jones
    attributes:
      corresponding: true

Roles

Author roles can be specified with either role or roles and can be any of:

A single string:

author: 
  role: "Conceived and designed the study"

An array of strings:

author: 
  role: 
    - conceptualization
    - methodology

An array of key-value pairs of the form role: contribution:

author: 
  role: 
    - conceptualization: lead
    - methodology: supporting

If a role matches one of the CRediT roles or their aliases, the additional properties vocab-identifier, vocab-term, and vocab-term-indentifier, will be added to the role with the appropriate value from the CRediT specification.

Arbitrary Metadata

The normalized authors schema at the top level is a closed schema. Unrecognized keys that are passed in the root of authors will be normalized under the metadata key. For example:

author:
  name: Norah Jones
  corresponding: true
  custom-info: "custom value"

would be normalized into:

author:
  - name:
      given: Norah
      family: Jones
      literal: Norah Jones
    attributes:
      corresponding: true
    metadata:
      custom-info: "custom value"

Keys that are normalized into metadata should be considered potentially template specific and may not be present or depended upon when implementing a template.

Affiliations Schema

The complete, normalized affiliations schema is defined as:

affiliations:
  - id: string
    number: number
    name: string
    department: string
    group: string
    address: string
    city: string
    region: string
    country: string
    postal-code: string
    url: string

Parsing Notes

You may specify either state or region- either will be normalized into the region key.
If you specify only a string for an affiliation, it will be used as the name of affiliation.
You may omit an id and the id will be automatically generated (a simple counter based id will be used).
The url field may also be populated by an affiliation-url key in the author, which preserves compatibility with Distill metadata for authors and affiliations.

Combinations

To combine the above schemas, users may specify author and affiliations in a number of different ways. Each will be normalized into the standard schema described above.

Inline Affiliations

You may write affiliations as simple string or complex affiliations inline. For example:

author:
  - name: Norah Jones
    affiliations:
      - Carnegie Mellon University
      - University of Chicago

author:
  - name: Norah Jones
    affiliations:
      - name: Carnegie Mellon University
        city: Pittsburgh
        state: PA
      - name: University of Chicago
        city: Chicago
        state: IL

Reference Affiliations

You may write out the affiliations into a separate key and only reference the affiliation in the author. For example:

author:
  - name: Norah Jones
    affiliations:
      - ref: cmu
      - ref: chicago
affiliations:
  - id: cmu
    name: Carnegie Mellon University
    city: Pittsburgh
    state: PA
  - id: chicago
    name: University of Chicago
    city: Chicago
    state: IL

Inline References

You may also assign ids to affiliations created in the author key and use those ids as references in other authors. For example:

author:
  - name: Norah Jones
    affiliations:
      - id: cmu
        name: Carnegie Mellon University
        city: Pittsburgh
        state: PA
      - id: chicago
        name: University of Chicago
        city: Chicago
        state: IL
  - name: John Hamm
    affiliations:
      - ref: cmu
      - name: University of California, San Diego
        city: San Diego
        state: CA