Writing funding items

The task of writing funding 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 funding is that while affiliation files are simple and can thus be given as either csv or tsv format, funding items in ORCID are more complex requiring a structured file format such as the json or YAML formats to convey. The Hub accepts batches of funding 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 funding data must comply with the structure of the ORCID V2.0/V2.1 funding 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}, ...], funding},{"invitees":[{invitee4}, {invitee5}, ...], funding2}, ...]

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

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

Example funding task in json

Show/Hide Code

[{
		"invitees": [
			{"identifier": "00001", "email": "[email protected]", "first-name": "Alice", "last-name": "Contributor 1", "ORCID-iD": "0000-0002-9207-4933", "put-code": null, "visibility": "PRIVATE"}, 
			{"identifier": "00002", "email": "[email protected]", "first-name": "Bob", "last-name": "Contributor 2", "ORCID-iD": null, "put-code": null, "visibility":null}, 
			{"identifier": "00003", "email": "[email protected]", "first-name": "Eve", "last-name": "Contributor 3", "ORCID-iD": null, "put-code": null, "visibility":null}
		],
		"amount": {"currency-code": "NZD", "value": "300000"},
		"organization-defined-type": {"value": "Fast-Start"},
		"organization": {
			"disambiguated-organization": {
				"disambiguated-organization-identifier": "http://dx.doi.org/10.13039/501100009193",
				"disambiguation-source": "FUNDREF"
			},
			"name": "Marsden Fund",
			"address": {"city": "Wellington", "country": "NZ"}
		},
		"contributors": {
			"contributor": [{
					"contributor-attributes": {"contributor-role": "lead"},
					"credit-name": {"value": "Associate Professor A Contributor 1"},
					"contributor-orcid": {
						"uri": "https://sandbox.orcid.org/0000-0002-9207-4933",
						"path": "0000-0002-9207-4933",
						"host": "sandbox.orcid.org"
					}
				}, {
					"contributor-attributes": {"contributor-role": "co_lead"},
					"credit-name": {"value": "Dr B Contributor 2"}
				}, {
					"contributor-attributes": {"contributor-role": ""},
					"credit-name": {"value": "Dr E Contributor 3"}
				}
			]
		},
		"title": {"title": {"value": "This is the project title"}},
		"short-description": "This is the project abstract",
		"end-date": {"year": {"value": "2021"}},
		"start-date": {"year": {"value": "2018"}},
		"type": "CONTRACT",
		"external-ids": {"external-id": [
      {"external-id-value": "XXX1701", "external-id-relationship": "SELF", "external-id-type": "grant_number"}
    ]}
}, 
 {
		"invitees": [
      {"identifier": "00004", "email": "[email protected]", "first-name": "Felix", "last-name": "Contributor 4", "ORCID-iD": null, "put-code": null, "visibility":null}
		],
		"amount": {"currency-code": "NZD", "value": "800000"},
		"organization-defined-type": {"value": "Standard"},
		"organization": {
			"disambiguated-organization": {
				"disambiguated-organization-identifier": "http://dx.doi.org/10.13039/501100009193",
				"disambiguation-source": "FUNDREF"
			},
			"name": "Marsden Fund",
			"address": {"city": "Wellington","country": "NZ"}},
		"contributors": {
			"contributor": [{
					"contributor-attributes": {"contributor-role": "lead"},
					"credit-name": {"value": "Associate Professor F Contributor 4"},
					"contributor-email": {"value": "[email protected]"}
				}
			]
		},
		"title": {"title": {"value": "This is another project title"}},
		"short-description": "This is another project abstract",
		"end-date": {"year": {"value": "2021"}},
		"start-date": {"year": {"value": "2018"}},
		"type": "CONTRACT",
		"external-ids": {
			"external-id": [
        {"external-id-value": "XXX1702", "external-id-relationship": "SELF", "external-id-type": "grant_number"}
			]
		}
	}
]

You can download example_fundings.json here.

Example funding task in yaml

Show/Hide Code

---
- invitees:
  - identifier: '00001'
    email: [email protected]
    first-name: Alice
    last-name: Contributor 1
    ORCID-iD: 0000-0002-9207-4933
    put-code: null
    visibility: 'PUBLIC'
  - identifier: '00002'
    email: [email protected]
    first-name: Bob
    last-name: Contributor 2
    ORCID-iD: null
    put-code: null
    visibility: null
  - identifier: '00003'
    email: [email protected]
    first-name: Eve
    last-name: Contributor 3
    ORCID-iD: null
    put-code: null
    visibility: null
  amount:
    currency-code: NZD
    value: '300000'
  organization-defined-type:
    value: Fast-Start
  organization:
    disambiguated-organization:
      disambiguated-organization-identifier: http://dx.doi.org/10.13039/501100009193
      disambiguation-source: FUNDREF
    name: Marsden Fund
    address:
      city: Wellington
      country: NZ
  contributors:
    contributor:
    - contributor-attributes:
        contributor-role: lead
      credit-name:
        value: Associate Professor A Contributor 1
      contributor-orcid:
        uri: https://sandbox.orcid.org/0000-0002-9207-4933
        path: 0000-0002-9207-4933
        host: sandbox.orcid.org
    - contributor-attributes:
        contributor-role: co_lead
      credit-name:
        value: Dr B Contributor 2
    - contributor-attributes:
        contributor-role: ''
      credit-name:
        value: Dr E Contributor 3
  title:
    title:
      value: This is the project title
  short-description: This is the project abstract
  end-date:
    year:
      value: '2021'
  start-date:
    year:
      value: '2018'
  type: CONTRACT
  external-ids:
    external-id:
    - external-id-value: XXX1701
      external-id-relationship: SELF
      external-id-type: grant_number
- invitees:
  - identifier: '00004'
    email: [email protected]
    first-name: Felix
    last-name: Contributor 4
    ORCID-iD: null
    put-code: null
    visibility: null
  amount:
    currency-code: NZD
    value: '800000'
  organization-defined-type:
    value: Standard
  organization:
    disambiguated-organization:
      disambiguated-organization-identifier: http://dx.doi.org/10.13039/501100009193
      disambiguation-source: FUNDREF
    name: Marsden Fund
    address:
      city: Wellington
      country: NZ
  contributors:
    contributor:
    - contributor-attributes:
        contributor-role: lead
      credit-name:
        value: Associate Professor F Contributor 4
  title:
    title:
      value: This is another project title
  short-description: This is another project abstract
  end-date:
    year:
      value: '2021'
  start-date:
    year:
      value: '2018'
  type: CONTRACT
  external-ids:
    external-id:
    - external-id-value: XXX1702
      external-id-relationship: SELF
      external-id-type: grant_number

You can download example_fundings.yaml here.

funding_schema.yaml

Any funding task file that is uploaded is first validated against the funding_schema.yaml

Show/Hide Code

You can download funding_schema.yaml here.