XSD 1.2 Update

XSD 1.2 is now available on the production ORCID Registry and sandbox as a stable release version. On April 1, 2015 we will update the default ORCID Message Schema from version 1.1 to 1.2, and we will no longer support version 1.1 or release candidate versions of 1.2. After April 1, integrations that have not updated to version 1.2 may not work correctly.

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

For more information about the Schema updating process and how release candidates work see ORCID XSD Versioning.

The new XSD for Version 1.2 can be found at:
https://github.com/ORCID/ORCID-Source/blob/master/orcid-model/src/main/resources/orcid-message-1.2.xsd

API calls can be made using version 1.2 by specifying "/v1.2" in the endpoint URI. For, examples:

  • http://api.orcid.org/v1.2/0000-0002-1982-1816/orcid-profile
  • http://api.sandbox.orcid.org/v1.2/0000-0002-1825-0097/orcid-works/

 

XSD 1.2 is now available on the production ORCID Registry and sandbox as a stable release version. On April 1, 2015 we will update the default ORCID Message Schema from version 1.1 to 1.2, and we will no longer support version 1.1 or release candidate versions of 1.2. After April 1, integrations that have not updated to version 1.2 may not work correctly.

 

Who is affected?

All integrations that read from, write to, or create ORCID records are affected by this change. Integrations that use the API only to authenticate ORCID iDs are not affected.

If your integration Using scopes Action Needed
Reads from, Writes to, or Creates ORCID Records Any scopes ending in:

/read-limited
/create
/update

Update all API calls to use v1.2 in endpoint URL

Update XML files to use v1.2 in schema location and message version

Adds Works and/or Funding items /orcid-works/create
/funding/create
All actions listed above AND provide an external-identifier element for each item
Gets a user's authenticated ORCID iD only (and does not read from/write to ORCID records) /authenticate No action needed

Now - April 1, 2015

Either version 1.1, version 1.2, or any release candidate versions 1.2_rc1 to 1.2_rc7 can be used. During this time, version 1.1 will remain the default.

After April 1, 2015

Version 1.2 will be the default version. Versions 1.1 and release candidate versions of 1.2 will not be supported.

Integrations affected by these changes are encouraged to contact us at support@orcid.org for assistance in making this transition.

 

Migration Checklist:

  • If you are reading or writing to ORCID records, update the version number in your call and XML files to 1.2, as soon as your system is updated.
  • If you are reading information, update you system to expect the affiliations and funding sections and new work identifiers.
  • If you are reading source information from ORCID records make sure your system can accommodate the new client iD format and source element structure.
  • If you are writing works or funding items to ORCID records, you must start including an external-identifier with each work or funding item (for works where you have no identifier we suggest creating an identifier and recording it with the type source-work-id)

 

Changes from 1.1 to 1.2

New format client iDs

  • As of November, new clients issued have a different format (previously issued clients iDs had the same format as ORCID iDs). The new format is 20 characters long, alpha-numeric and starts with the code "APP" an example of the new client iD is APP-5G54N5YFOKGV5Z0X. The 1.2 schema will validate files with either format of client iD in a source element.

Source

  • All elements that record source information will now use the source field and the format shown below. These elements are: <orcid-history>, <external-identifier>, <affiliation>, <orcid-work>, and <funding>. The exception to this is the <email> field where source is recorded as an attribute. The source element is system generated and should not be included when writing information to a record
 <source>
   <source-orcid>
      <uri>https://orcid.org/APP-5G54N5YFOKGV5Z0X</uri>
       <path>APP-5G54N5YFOKGV5Z0X</path>
       <host>orcid.org</host>
   </source-orcid>
   <source-name>Test Credentials</source-name>
   <source-date>2014-12-05T08:33:57.153Z</source-date>
</source>

ORCID history

  • Creation method "website" has been deprecated for newly created records, "Direct" or "Member-referred" are used instead. The "API" option is also still available.
  • Added field <verified-email> contents are either "true" or "false."
  • Added field <verified-primary-email> contents are either "true" or "false."
  • The <source> elements is updated to new source format, see above

ORCID bio

  • Added <source> element to <external-identifier> following the new source format described above

ORCID activities

  • Removed unused sections for orcid-grants and orcid-patents (patent information can now be recorded in ORCID works)
  • Added funding (see XML for funding)
  • Added affiliations (see XML for affiliations)

ORCID work

  • <work-external-identifiers> is now required
  • Added <created-date> and <last-modified-date> elements
  • <work-source> element changed to <source> with the new format described above
  • <language-code> contents now must be selected from an enumerated list of ISO 639-1 codes.
  • New work external identifier types added:  Agricola identifier (agr), Chinese biological abstracts (cba), CiteSeer (cit), CiteXplore submission (ctx), EThOS (ethos), NHS Evidence (hir), patent number (pat), local identifier (source_work_id), Uniform resource identifier (uri), Uniform resource name (urn), and Web of Science™ identifier (wosuid).  For a full list see Supported work identifiers.

     

    Additional Updates

    In addition to the changes to the scheme listed above we also wanted to make you aware of other updates to the ORCID API.

    Long live tokens

    How the lifespan of access tokens has changed, and long lived tokens for adding and updating information can now be requested. See ORCID API Enabling Automatic Updates.

    Refresh tokens

    Refresh tokens will stop being returned with access tokens generated via OAuth. You must update your system to no longer look for or store refresh tokens.

     

    Questions?

    Please contact us at support@orcid.org with questions or concerns.