Skip to main content
Version: 2.x

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, for a key the input carries. A reference input can also take keys from its reference type: each such key gives the picked reference's ID, name, description, or the field the type assigns it.
  • In a list, each picked reference produces its own entry, with the answer's other values copied into each: two organisations picked in one answer give two organisations entries. Reference inputs that fill the same keys are alternatives; inputs that fill different keys are combined, one pick of each.
  • 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.
  • A reference input that takes identifier, date, or access keys only through its reference type gets one reference made from the file: its ID from the type's Reference ID key, its name, description, and fields from the type's other keys. OpenCDMP links it to an existing reference of the type with the same ID, or adds it as a new reference.