Writing works items

The task of writing works is very similar to writing affiliations, i.e.,

  • a batch file containing information to be written to ORCID records, together with the email or ORCID iD of the researcher/contributors to be affected, is uploaded to the Hub.

  • the Hub then either sends the people identified email invitations and/or uses the access tokens it already has to write the information to their ORCID records.

The main difference in writing works is that while affiliation files are simple and can thus be given as either csv or tsv format, works in ORCID are more complex requiring a structured file format such as the json or YAML formats to convey. The Hub accepts batches of works items where each item contains an initial invitees block (detailing the names, email, and optionally ORCID iD and put-code for each individual to be affected) and following that invitee block, the data to be written to each invitee’s ORCID record. The work data must comply with the structure of the ORCID V2.0/V2.1 works schema, but omit put-code. If the task describes an update to existing information in a users ORCID record the put-code will not apply to all invitees; instead specify each put-code in the data of the relevant invitee:

[{"invitees":[{invitee1}, {invitee2}, ...], work},{"invitees":[{invitee4}, {invitee5}, ...], work2}, ...]

Example files can be found here: Example works task in json and Example works task in yaml, while any uploaded works file will be validated against the work_schema.yaml.

For more information and guidance on the structure expected of works task files see here: Works schema for ORCID API 2.0/2.1

Example works task in json

Show/Hide Code

[
	{
		"invitees": [
			{"identifier": "00001", "email": "contributor1@mailinator.com", "first-name": "Alice", "last-name": "Contributor 1", "ORCID-iD": "0000-0002-9207-4933", "put-code": null, "visibility": null},
			{"identifier": "00002", "email": "contributor2@mailinator.com", "first-name": "Bob", "last-name": "Contributor 2", "ORCID-iD": null, "put-code": null, "visibility": null}
		],
		"path": null,
		"title": {
			"title": {"value": "This is a title"},
			"subtitle": null,
			"translated-title": {"value": "हिंदी","language-code": "hi"}
		},
		"journal-title": {"value": "This is a journal title"},
		"short-description": "xyz this is short description",
		"citation": {"citation-type": "FORMATTED_UNSPECIFIED", "citation-value": "This is citation value"},
		"type": "BOOK_CHAPTER",
		"publication-date": {
			"year": {"value": "2001"},
			"month": {"value": "1"},
			"day": {"value": "12"},
			"media-type": null
		},
		"external-ids": {
			"external-id": [{
					"external-id-type": "bibcode",
					"external-id-value": "sdsds",
					"external-id-url": {"value": "http://url.edu/abs/ghjghghj"},
					"external-id-relationship": "SELF"
				}
			]
		},
		"url": null,
		"contributors": {
			"contributor": [
				{"contributor-attributes": {"contributor-sequence": "FIRST", "contributor-role": "AUTHOR"},
					"credit-name": {"value": "Associate Professor Alice"},
					"contributor-orcid": {
						"uri": "https://sandbox.orcid.org/0000-0002-9207-4933",
						"path": "0000-0002-9207-4933",
						"host": "sandbox.orcid.org"
					}
				},
				{"contributor-attributes": {"contributor-sequence": "ADDITIONAL", "contributor-role": "AUTHOR"},
					"credit-name": {"value": "Dr Bob"}
				}
			]
		},
		"language-code": "en",
		"country": {"value": "NZ"}
	}
]

You can download example_works.json here.

Example works task in yaml

Show/Hide Code

---
- invitees:
  - identifier: '00001'
    email: contributor1@mailinator.com
    first-name: Alice
    last-name: Contributor 1
    ORCID-iD: null
    put-code: null
    visibility: null
  - identifier: '00002'
    email: contributor2@mailinator.com
    first-name: Bob
    last-name: Contributor 2
    ORCID-iD: null
    put-code: null
    visibility: null
  title:
    title:
      value: This is a title
    subtitle: 
    translated-title:
      value: हिंदी
      language-code: hi
  journal-title:
    value: This is a journal title
  short-description: xyz this is short description
  citation:
    citation-type: FORMATTED_UNSPECIFIED
    citation-value: This is citation value
  type: BOOK_CHAPTER
  publication-date:
    year:
      value: '2001'
    month:
      value: '1'
    day:
      value: '12'
    media-type: 
  external-ids:
    external-id:
    - external-id-type: bibcode
      external-id-value: sdsds
      external-id-url:
        value: http://url.edu/abs/ghjghghj
      external-id-relationship: SELF
  url: 
  contributors:
    contributor:
    - contributor-attributes:
        contributor-sequence: 'FIRST'
        contributor-role: AUTHOR
      credit-name:
        value: Associate Professor Alice
      contributor-email:
        value: alice.333456@mailinator.com
      contributor-orcid:
        uri: https://sandbox.orcid.org/0000-0002-9207-4933
        path: 0000-0002-9207-4933
        host: sandbox.orcid.org
    - contributor-attributes:
        contributor-sequence: 'ADDITIONAL'
        contributor-role: AUTHOR
      credit-name:
        value: Dr Bob
  language-code: en
  country:
    value: NZ

You can download example_works.yaml here.

work_schema.yaml

Any works task file that is uploaded is first validated against the work_schema.yaml

Show/Hide Code

You can download work_schema.yaml here.