Skip to main content
Version: 2.x (upcoming)

RAiD JSON Transformer — Semantics Reference

The RAiD JSON file transformer exports plans to JSON files conforming to the RAiD metadata schema v1.6.x, and imports such files as new plans.

To populate a RAiD JSON field, assign the semantic listed below to a question of the plan blueprint or of an asset template. Values outside the RAiD vocabularies are dropped, and dates must be written as yyyy, yyyy-MM, or yyyy-MM-dd.

How the transformer resolves fields​

The transformer reads the blueprint's questions first, then the questions of each asset in the plan. Every semantic on this page works in both blueprints and asset templates.

  • Single blocks (identifier, date, and access): RAiD allows one of each. Every value takes the first answer found, so a blueprint answer wins over an asset's, and an earlier asset's over a later one. Within a repeating question, only the first answered item counts.
  • Lists (titles, descriptions, contributors, organisations, relatedObjects, alternateIdentifiers, alternateUrls, and relatedRaids): each answer to a question (each item of a repeating question) produces one entry, provided at least one of its values is valid. Blueprint entries come first, then those of each asset.
  • Empty blocks are not written: a block or list without any valid value is left out of the file.

How an answer is read:

  • Text inputs give their text, Yes/No and checkbox inputs true or false, number inputs the number, and date inputs yyyy-MM-dd.
  • Select and radio inputs give the value of the chosen option. To write a RAiD vocabulary value, use it as the option's value and give the option a readable label.
  • Reference inputs give the picked reference's value, for example its ROR or ORCID address.
  • Tags inputs give their first tag.

Values that are always set​

RAiD JSON fieldValue
titles[0].textThe plan title, as the primary title. Titles answered in the plan or its assets follow it.
titles[0].type.idhttps://vocabulary.raid.org/title.type.id/380 (Primary).
titles[0].type.schemaUrihttps://vocabulary.raid.org/title.type.schema/376.
titles[0].startDateThe date the plan was created (yyyy-MM-dd).
titles[0].endDateThe date the plan was finalized (yyyy-MM-dd), for a finalized plan.

identifier​

RAiD JSON fieldSemanticNotes
identifier.idraid.identifier.id
identifier.schemaUriraid.identifier.schemaUriSee identifier.schemaUri.
identifier.registrationAgency.idraid.identifier.registrationAgency.id
identifier.registrationAgency.schemaUriraid.identifier.registrationAgency.schemaUriSee registrationAgency.schemaUri.
identifier.owner.idraid.identifier.owner.id
identifier.owner.schemaUriraid.identifier.owner.schemaUriSee owner.schemaUri.
identifier.owner.servicePointraid.identifier.owner.servicePointA whole number; other answers are dropped.
identifier.licenseraid.identifier.licenseSee identifier.license.
identifier.versionraid.identifier.version

date​

RAiD JSON fieldSemanticNotes
date.startDateraid.date.startDateRequired by RAiD. Without an answer the block is left out, and the file does not validate against the RAiD schema.
date.endDateraid.date.endDate

access​

RAiD JSON fieldSemanticNotes
access.type.idraid.access.type.idRequired by RAiD. See access.type.id.
access.type.schemaUriraid.access.type.schemaUriRequired by RAiD. See access.type.schemaUri.
access.embargoExpiryraid.access.embargoExpiryRequired by RAiD for embargoed access.
access.statement.textraid.access.statement.textRequired by RAiD for embargoed access.
access.statement.language.idraid.access.statement.language.idSee statement language id.
access.statement.language.schemaUriraid.access.statement.language.schemaUriSee statement language schemaUri.

titles[]​

RAiD JSON fieldSemanticNotes
titles[].textraid.title.text
titles[].type.idraid.title.type.idSee title.type.id.
titles[].type.schemaUriraid.title.type.schemaUriSee title.type.schemaUri.
titles[].language.idraid.title.language.idSee title.language.id.
titles[].language.schemaUriraid.title.language.schemaUriSee title.language.schemaUri.
titles[].startDateraid.title.startDate
titles[].endDateraid.title.endDate

descriptions[]​

RAiD JSON fieldSemanticNotes
descriptions[].textraid.description.text
descriptions[].type.idraid.description.type.idSee description.type.id.
descriptions[].type.schemaUriraid.description.type.schemaUriSee description.type.schemaUri.
descriptions[].language.idraid.description.language.idSee description.language.id.
descriptions[].language.schemaUriraid.description.language.schemaUriSee description.language.schemaUri.

contributors[]​

Each contributor gets at most one position and one role. RAiD requires a contributor's identifier and schema URI, and a position with its identifier, schema URI, and start date.

RAiD JSON fieldSemanticNotes
contributors[].idraid.contributor.idFor example an ORCID address.
contributors[].schemaUriraid.contributor.schemaUriSee contributor.schemaUri.
contributors[].position[0].idraid.contributor.position.idSee position.id.
contributors[].position[0].schemaUriraid.contributor.position.schemaUriSee position.schemaUri.
contributors[].position[0].startDateraid.contributor.position.startDate
contributors[].position[0].endDateraid.contributor.position.endDate
contributors[].leaderraid.contributor.leaderSet when the answer is Yes or true, in any case; other answers leave it out.
contributors[].contactraid.contributor.contactSame rule as leader.
contributors[].role[0].idraid.contributor.role.idSee role.id.
contributors[].role[0].schemaUriraid.contributor.role.schemaUriSee role.schemaUri.

organisations[]​

Each organisation gets at most one role.

RAiD JSON fieldSemanticNotes
organisations[].idraid.organisation.idFor example a ROR address.
organisations[].schemaUriraid.organisation.schemaUriSee organisation.schemaUri.
organisations[].role[0].idraid.organisation.role.idSee role.id.
organisations[].role[0].schemaUriraid.organisation.role.schemaUriSee role.schemaUri.
organisations[].role[0].startDateraid.organisation.role.startDate
organisations[].role[0].endDateraid.organisation.role.endDate

relatedObjects[]​

Each related object gets at most one category.

RAiD JSON fieldSemanticNotes
relatedObjects[].idraid.relatedObject.id
relatedObjects[].schemaUriraid.relatedObject.schemaUriSee relatedObject.schemaUri.
relatedObjects[].type.idraid.relatedObject.type.idSee type.id.
relatedObjects[].type.schemaUriraid.relatedObject.type.schemaUriSee type.schemaUri.
relatedObjects[].category[0].idraid.relatedObject.category.idSee category.id.
relatedObjects[].category[0].schemaUriraid.relatedObject.category.schemaUriSee category.schemaUri.

alternateIdentifiers[]​

RAiD JSON fieldSemanticNotes
alternateIdentifiers[].idraid.alternateIdentifier.id
alternateIdentifiers[].typeraid.alternateIdentifier.typeFree text.

alternateUrls[]​

RAiD JSON fieldSemanticNotes
alternateUrls[].urlraid.alternateUrl.urlMust be a valid URI; other answers are dropped.

relatedRaids[]​

RAiD JSON fieldSemanticNotes
relatedRaids[].idraid.relatedRaid.id
relatedRaids[].type.idraid.relatedRaid.type.idSee relatedRaid.type.id.
relatedRaids[].type.schemaUriraid.relatedRaid.type.schemaUriSee relatedRaid.type.schemaUri.

Import​

Importing a RAiD JSON file creates a new plan:

  • The plan's title is the file's primary title, or its first title when none is marked primary.
  • The plan is public when access.type.id is open access, and restricted otherwise.
  • The identifier, date, and access values are written to the blueprint questions carrying their semantics. The lists are not read back, and no assets are created.