XSD 2.0 update

XSD 2.0 is now available on the production ORCID Registry and sandbox as a stable release version. On February 14 we will update the default ORCID Message Schema from v1.2 to v2.0, and we will no longer support v1.2 or release candidates of v2.0. v1.2 is expected to be sunset in the fourth quarter of 2017.

This article describes this update and outlines changes that API users will need to put in place.

We’ll be running monthly webinars on the changes between 1.2 and 2.0 and are happy to work with you in the transition.

Contents

Summary

The update from v1.2 to v2.0 includes significant updates that affects the speed and flexibility of your interactions with the ORCID API. At a high level, these include:

The new XSD for version 2.0 can be found in the ORCID GitHub repository. No further major revisions to v2.0 are planned. Further changes will be expressed in v2.1.

For more information about the schema updating process and how release candidates work, see

Meta: Documentation

Documentation on the ORCID API has been split in three locations:

  • GitHub: ORCID XSD, example files, full list of API scopes, full list of API calls (with examples)
  • Swagger (Sandbox: Public API, Member API; Production: Public API, Member API): List of all possible API calls on public and member API, ability to try calls using your own credentials
  • Member support centre: Documentation to support members building integrations with the ORCID Registry, including workflows of sample integrations (e.g. institutional repositories, manuscript submission systems), communications, and tutorials on searching, reading, and updating ORCID records using the ORCID API

Migration plan

February 14, 2017: Default updated from v1.2 to v2.0; no support provided for v1.2, v2.0 release candidates (v2.0_rcX), and earlier versions.

Quarter 4 (October-December), 2017: Sunset v1.2, v2.0_rcX, and earlier versions.

Am I affected?

All integrations that read or update ORCID records are affected by the 2.0 release. Integrations which use the API only to authenticate ORCID iDs are mostly not affected -- but you should check to ensure that your token endpoints are correct.

If your integration

Using scopes

Action needed

Reads ORCID records

Any scopes ending in:
/read-limited

  • Store and use refresh tokens
  • Update all API calls to use v2.0 endpoints
  • Update your system to expect information in the v2.0 message schema format
  • Update all scopes to use single /read-limited for the entire record
  • Ensure that you use using HTTPS on calls and redirect URIs, as well as new token endpoints
  • If you are reading works or funding items, add a step to read each item’s full view based on 8978its put code (see below)

Updates (writes to) ORCID records

Any scopes ending in:
/create
/update

Searches the ORCID API

/read-public

  • Update all API calls to use v2.0 endpoints
  • Update to expect search results to only include the ORCID iD, activities and biographical information will need to be accessed with a second call. (see below)

Get a user’s authenticated ORCID iD only

/authenticate

  • Ensure that you use using HTTPS for calls and redirect URIs, as well as new token endpoints
  • Recommended: Update your workflow to use the /authenticate token to read records, instead of /read-public token
  • Recommended: Store access tokens (and refresh tokens) to indicate an iD has been authenticated

Changes from 1.2 to 2.0

HTTPS and token endpoints

All calls to the public and member API to read and update ORCID records (GET, POST, PUT, DELETE) must start with HTTPS.

Redirect URIs must also start with HTTPS.

Token endpoints (the url used when exchanging an authorization code for an access token) are now simplified and are the same for public and member API:

  • Sandbox: https://sandbox.orcid.org/oauth/token
  • Production: https://orcid.org/oauth/token

Streamlined scopes

We’ve consolidated our scopes into three main scopes that will allow you full read (limited) and update access to the ORCID record.

Your previous access tokens will still work at the access levels for which they were originally issued. For example, if you have an access token with the scope /funding/read-limited, then you will still be able to use that token to read public and trusted (limited-access) funding data, but you will not be able to use that access token to read trusted works data -- unless you are that data's source. 

Old scope

New scope

/authenticate

/authenticate
(now includes /read-public scope)

/orcid-profile/read-limited

/read-limited

/orcid-bio/read-limited

/orcid-works/read-limited

/orcid-bio/update

/person/update

/orcid-bio/external-identifiers/create

/orcid-works/create

/activities/update

/orcid-works/update

/affiliations/create

/funding/create

/funding/update

/read-public

/read-public

 

/webhook

/webhook

Multiple XSD

The schema has been split into multiple files, all of which are stable and stored in the ORCID GitHub repository. The schema contains several changes, the most evident of which are namespaces and the use of common elements throughout multiple sections of the ORCID record. For more information about the 2.0 schema see the example files in our GitHub repository or our guide on reading a record with the 2.0 schema.

Example:

1.2 work

<work-title>
      <title>Work title</title>
</work-title>
<work-type>journal-article</work-type>
      <work-external-identifiers>
            <work-external-identifier>
                <work-external-identifier-type>doi</work-external-identifier-type>
                <work-external-identifier-id>
                10.12345/12.123.1424</work-external-identifier-id>
      </work-external-identifier>
</work-external-identifiers>

2.0 work

<work:title>
      <common:title>Work title</common:title>
</work:title>
<common:external-ids>
      <common:external-id>
          <common:external-id-type>doi</common:external-id-type>
            <common:external-id-value>
            10.12345/12.123.1424</common:external-id-value>
            <common:external-id-relationship>self</common:external-id-relationship>
      </common:external-id>
</common:external-ids>
<work:type>journal-article</work:type>

Summary views make reading faster

Previously, v1.2 allowed you to use a single call to receive the entire ORCID record -- all the public data available. For records populated with a high number of activities, this could result in extremely large file sizes, making things difficult to find and potentially putting a strain on our system and yours.

v2.0 allows you to use a single call to the API to get the researcher’s record, or to individual sections of the ORCID record; the funding, works, and peer review sections of the ORCID record are displayed in summary view.

Each item contains its path and unique put code, which you can use to call and receive further information. If multiple versions of a work, funding, or peer-review item have been added to the record, then they are grouped and each version’s display index -- the preferred source seen on the ORCID public record -- are included.

For example, the summary view of a grouped work will return only the work title, type, date, source, its unique identifiers and the identifier’s relationship to the work, and display index for each version of the item.

For more, see our guide on reading ORCID records.

Read and update items on an individual basis

Previously, v1.2 allowed you to use a single call to read or update an entire section of the ORCID record in full: biography, external personal identifiers, affiliations, works, or funding. As a result, if you wanted to read the full metadata of only one funding item, or make a small update of a only one work item, then you had to read or update the entire section.

v2.0 has simplified this process by implementing put codes. Individual items on the ORCID Registry now have their own put code, which can be used to read the full metadata for the item or to update or delete an item that your system has added to an ORCID record. Only one item can be edited or deleted at a time. Put codes are retroactive: items added in 1.2 and earlier have all been assigned put codes.

Items in general must also be read or added to a record one at a time. The exception is works -- works can be read in bulk (up to 50) and added in bulk (up to 100). Whenever a new item is added, its put code is returned by the ORCID API.

Grouped activities matching user interface

ORCID groups together multiple versions of the same work, funding, or peer review activity based on a unique shared identifier that has a self relationship with that item. v2.0 now provides support for this in the XSD, with the group serving as the parent item for all individual versions of the item.

Each item has a display index attribute which indicates its rank within its group. The highest display index is the preferred item selected by the researcher, items added via the API which have not been ranked by the researcher have a display index of 0.

New activity section: Peer review

ORCID introduced the peer review functionality in 2015 based on the CASRAI Peer Review Services data profile. Some organizations have worked with us as launch partners helping us to test this functionality, as well as other v2.0 features.

Peer review activity items can have as much or little detail as appropriate, and every peer review item requires its own group ID, an identifier used for aggregation purposes, e.g. a journal, publisher, conference.

During the testing phase, members had to request access to the peer review functionality; it is now available to all member API credentials.

For more, see our peer review workflow and #RecognizeReview with ORCID.

Support for multiple countries and regions

Previously, only one address -- a country or region -- was supported on the ORCID record. Multiple addresses can now be added to the ORCID record, and the user’s display preference is indicated in its display index number (higher display index numbers are at the top of the user ordered list).

Improvements for external identifiers

v2.0 introduces two new fields for external identifiers that aid in grouping items together and finding more information about the item in other systems. v2.0 also offers more flexible support for adding new external identifiers.

The external identifier’s relationship has two options -- self or part-of -- and defines the relationship of the item to the identifier. For example, if the work is a book chapter, and the identifier is the ISBN for the book, then the relationship would be “part of”; if the identifier is the DOI for the book chapter itself, then the relationship would be “self”.

The external identifier URL is the web address where a user or system can access more information about the item. It is an optional field..

If your organization creates and uses unique identifiers that are also used by other systems, you can request that we add them to the Registry -- contact us to find out more. A list of existing identifiers can be retrieved using the Identifier API.

More default search results

The API search has a slightly updated call and largely the same search fields and formatting. It has increased the default results from 10 to 100, and the maximum of results have increased from 100 to 200.

It also has changed the information returned in results. Previously, the biography section of the ORCID record was returned for each search result. This did not always include the actual term that was hit during the search, meaning that the full record would need to be read to learn what information was found. v2.0 takes a step out of this process and only returns the ORCID iDs of the records which were successful hits. You will then need to read the record to find the relevant data.

Affiliations search is coming soon -- keep a watch on our Current Development Trello board.

Updated error codes and messaging

We’ve added new descriptive error codes to the ORCID API which provide clear information when something has gone wrong. If you still can’t figure out what’s happened, you can always contact us with the error code.

Non-editable fields

Previously, v1.2 allowed members to update a researcher’s given name, family name, or biography. This had the potential to overwrite the researcher’s preferred name, or how they chose to describe themselves in the system, or even lock them out from editing that data.

The v2.0 no longer has edit access to any of these fields. The logic behind this is that the user has chosen to add these fields themselves, and no party can edit data added by another party.

Know when items were created and modified

v2.0 introduces new metadata for each item on the ORCID record. When querying an item, you’ll find the date it was created, the date it was last modified, its source, and whether that source is the ORCID record holder or another member’s API client. The creation create and last modified date are also provided for each item, group, and section of the record, as well as for the ORCID record as a whole.

As with put codes, the source metadata has also been made visible for items added using v1.2 and earlier.