Documentation

Affiliations and ROR

This guide gives markup examples for members registering affiliations by direct deposit of XML. As of schema version 5.3.0 we’ve introduced a new tag that supports both affiliated institution names and select identifiers, including ROR. This change is made across contributor metadata in all record types.

Affiliation metadata consists of a repeatable element that contains the following:

Requirements:

• For each affiliation, you must at minimum include an institution identifier (institution_id) or an institution name (institution_name). A ROR ID is recommended as we plan to integrate ROR data into our APIs in the future.
• You should include an identifier wherever possible, to improve discovery, disambiguate, and make affiliations machine actionable.
• You may include optional metadata including an acronym (institution_acronym), a place (institution_place), and a department (institution_department). Most of this metadata is made redundant by identifiers, so include only if an identifier is not available or if the identifier is not sufficiently granular (as with departments).

Institution identifiers

We currently support 3 institution identifiers: ROR, Wikidata, and ISNI. We do some basic validation for each identifier provided in your XML:

• ROR: must begin with https://ror.org/ (full regex used for validation is https://ror\\.org/0[^ilo]{6}\\d{2})
• Wikidata: must begin with https://www.wikidata.org/entity/ (full regex used for validation is https://www\\.wikidata\\.org/entity/([qQ]|[pP]|[lL])\\d+)
• ISNI: should begin with https://isni.org/isni but https://www.isni.org/isni is also allowed (full regex used for validation is https://www\\.isni\\.org/isni/\\d{15}(x|[0-9])

Affiliation examples

There are multiple ways to mark up an affiliation depending on what metadata is available - a ROR ID may be provided on its own as it’s all we need to identify an organization:

<affiliations>
  <institution>
    <institution_id type="ror">https://ror.org/05gq02987</institution_id>
  </institution>

This example includes department information to supplement the ROR ID:

<affiliations>
  <institution>
    <institution_id type="ror">https://ror.org/01bj3aw27</institution_id>
    <institution_department>Office of Environmental Management</institution_department>
  </institution>
</affiliations>

This affiliation does not have an identifier, so additional metadata is useful:

<institution>
    <institution_name>Tinker Fan Club</institution_name>
    <institution_acronym>TinFC</institution_acronym>
    <institution_place>Boston, MA</institution_place>
    <institution_department>Office of Environmental Management</institution_department>
</institution>

As mentioned above a ROR identifier is preferred, but ISNI and Wikidata identifiers are also supported and will be passed on to our metadata users via our REST and XML APIs.

Crossref and JATS

Crossref affiliation metadata easily maps to JATS and the JATS4R affiliation recommendations. For example, a basic affiliation with name only is tagged in JATS as:

<contrib-group>
<contrib contrib-type=”author”>
<name>
<surname initials=”M”>Mitchell</surname>
<given-names initials=”AP”>Aaron P.</given-names>
</name>
<aff>Carnegie Mellon University</aff>
</contrib>
</contrib-group>

and should be tagged for Crossref use as

<affiliations>
 	<institution>
		<institution_name>Carnegie Mellon University</institution_name>
	</institution>
</affiliations>

This example contains a JATS-tagged affiliation with an institution ID:

<aff id="aff1">
<label>a</label>
<institution-wrap>
<institution-id institution-id-type=”ror”>https://ror.org/03vek6s52
</institution-id>
<institution>Harvard University</institution></institution-wrap>
<institution-wrap>
<institution-id institution-id-type=”ror”>https://ror.org/000cs1t14
</institution-id>
<institution>Harvard NeuroDiscovery Center</institution>
</institution-wrap>
</aff>

and should be tagged for Crossref use as:

<affiliations>
 	<institution>
		<institution_name>Harvard University</institution_name>
		<institution_id type=”ror”>https://ror.org/03vek6s52</institution_id>
	</institution>
	<institution>
		<institution_name>Harvard NeuroDiscovery Center</institution_name>
		<institution_id type=”ror”>https://ror.org/000cs1t14</institution_id>
	</institution>
</affiliations>

Samples of full XML files containing our new affiliation metadata are available on our GitLab repository.