Metadata Schema

This page provides documentation for the JSON objects returned by Sherpa APIs. This is intended to be used as reference for developers while building against our APIs.

Phrases

Phrases for discrete value are included in the JSON returned by the API. The general pattern is that phrases appear in the same scope, with the same name as the field with a '_phrases' suffix. For example:

{
  "colour" : "blue",
  "colour_phrases" : [
    {
      "value" : "blue",
      "phrase" : "Blue",
      "language" : "en"
    }
  ],
  "person" : {
    "name" : "John Smith",
    "clothing" : ["tshirt", "jeans"],
    "clothing_phrases" : [
      {
        "value" : "tshirt",
        "phrase" : "T-Shirt",
        "language" : "en"
      },
      {
        "value" : "jeans",
        "phrase" : "Jeans",
        "language" : "en"
      }
    ]
  }
}

Notes:

Only English is currently supported, but there is scope for further language support.
If a field does not have an associated _phrases, then it is a text, numeric or object type.
Ordering of names in a JSON object is not defined. Be aware that an _phrases array may not be adjacent to its associated field.

Primary Objects

Notes:

For brevity, _phrase elements are omitted.
Preferred names and titles are generated automatically from the name and title fields to simplify objects in some contexts.
Empty values should not be included. If something is missing, it's probably because it's not set.

common to all types

All types have a 'system_metadata' section with the following fields:

system_metadata

id	integer: the Sherpa id of this object
publicly_visible	value("yes","no"): Is this object publicly visible?
date_created	date: the date this object was first created
date_modified	date: the date this object was last modified
uri	URL: the identity address of this object

funder

funder_metadata

Integer: the Sherpa ID for this item

name

array of objects: the name of the funder

name	text: the name of the funder
acronym	text: a short-form for the name
preferred	value('name', 'acronym'): which is preferred
language	value(two-letter language code): the language of this value

Note that this is a multilingual field and should only have one entry per language.

url

URL: the url of the funder

country

value(two letter country code): the country of the funder

notes

text: notes about the funder record

groups

array of objects: groups this funder belongs to

name	text: the preferred name of the funder
uri	URL: the Sherpa address of the funder group
id	integer: The Sherpa id of the funder group
type	value("funder_group"): included for system reasons

identifiers

array of objects: identifiers associated with this funder

identifier	text: the identifier
type	value('fundref', 'ror', 'other'): the identifier type

open_access_publications_policy

urls

multiple object: URLs for the funder's publications policy documents

description	text: Description of the document linked to
type	value('policy', 'statement', 'guidance', 'information'): the type of document
url	URL: the address of the document

scope

multiple value('applies_to_funded_projects', 'applies_to_work_using_facilities'): the scope of the policy

special_conditions

array of text: Free-text conditions (things that don't fit easily into the data model)

notes

text: notes about the policy

policy_effective_data

object: the date the policy became effective

for_new_projects	date: date for new projects
for_existing_projects	date: date for existing projects
earlier_compliance_encouraged	value('yes','no'): whether earlier compliance is encouraged

archiving_policy

object: the funder's archiving policy

requirement

value('requires', 'encourages', 'does_no_mention', 'no_policy_for'): The funder's overall requirement

conditions

array of value('respect_publisher_rights', 'author_oa_copyright_retention_required', 'author_copyright_retention_encouraged', 'include_publisher_url', 'archive_revisions'): Conditions of the funder

special_conditions

array of text: Free-text conditions (no option exists in conditions)

license

array of object

license	value('cc_by_nd', 'cc_by', 'cc_by_nc', 'cc_by_nc_nd', 'cc_by_nc_sa', 'cc_by_sa', 'cc0', 'cc_public_domain', 'cc_gnu_gpl', 'cc_gnu_lgpl', 'open_government_licence', 'all_rights_reserved', 'bespoke_license'): the name of the license
version	text: the license version
applies	value('to_all', 'when_paid_oa', 'when_not_paid_oa', 'when_oa_journal'): when this license applies

what

object

types

array of value('conference_papers', 'executive_summaries', 'unspecified_documents', 'peer_reviewed_publications', 'any_publications', 'project_reports', 'public_summaries'): the types of publication the policy covers

versions

array of object

version	value('publishers_version', 'authors_final_version', 'full_text', 'unspecified_version', 'link_to_oa_full_text', 'metadata_only'): the version
requirement	value('required', 'alternative', 'preferred', 'optional', 'example', 'forbidden'): the requirement

when

object

when

value('at_earliest_opportunity', 'on_acceptance', 'on_publication', 'after_publisher_embargo', 'unspecified'): when the archiving should happen

within

object

start	value('on_acceptance', 'on_publication', 'unspecified'): when the within period starts
amount	integer: the amount of the period
units	value('days', 'weeks', 'months', 'years'): the units of the period

permitted_embargo

object

amount	integer: the amount of the embargo
units	value('days', 'weeks', 'months', 'years'): the units of the embargo

metadata_deposit_at_date_of_publication_required

value('yes','no): whether the metadata should be made available at date of publication

where

object

location

array of object

location	value('author_website', 'institutional_repository', 'national_repository', 'disciplinary_repository', 'any_appropriate_repository', 'named_repository', 'unspecified'): the location
constraint	value('required', 'alternative', 'preferred', 'optional', 'example', 'forbidden'): constraint

named_repositories

array of object

name	text: the name of the location
url	URL: the url of the location
constraint	value('required', 'alternative', 'preferred', 'optional', 'example', 'forbidden'): constraint

publishing_policy

object

requirement

value('requires', 'encourages', 'does_no_mention', 'no_policy_for'): the overall requirement for OA publishing

where

object

location	value('peer_reviewed_oa_journal', 'paid_oa', 'unspecified')
constraint	value('required', 'alternative', 'preferred', 'optional', 'example', 'forbidden')

conditions

array of value('published_version_archiving', 'funder_may_reimburse', 'costs_in_application'): conditions

special_conditions

array of text: Free-text conditions (no option exists in conditions)

publisher_must_deposit

array of objects: locations the publisher must deposit in

version	value('publishers_version', 'authors_final_version'): the version of the publication
location	value('pubmed_central', 'europe_pmc'): the location the publisher must deposit
applies	value('when_paid_oa','when_not_paid_oa'): when this applies (always applies if not set)

open_access_data_archiving_policy

requirement

value('requires', 'encourages', 'does_no_mention', 'no_policy_for'): The funder's overall requirement

scope

array of value('applies_to_funded_projects', 'applies_to_work_using_facilities'): The scope of the policy

where

location

array of objects: where the data should be archived

location	value('author_website', 'institutional_repository', 'national_repository', 'disciplinary_repository', 'any_appropriate_repository', 'named_repository', 'unspecified'): the location
constraint	value('required', 'alternative', 'preferred', 'optional', 'example', 'forbidden'): constraint

named_repositories

array of objects: named locations for archive

name	text: the name of the location
url	URL: the url of the location
constraint	value('required', 'alternative', 'preferred', 'optional', 'example', 'forbidden'): constraint

what

array of value('unpublished_data', 'research_data', 'specimens_and_samples', 'patented_inventions', 'metadata', 'documentation', 'source_code', 'unspecified'): What the policy applies to

urls

multiple object: URLs for the funder's data policy documents

description	text: Description of the document linked to
type	value('policy', 'statement', 'guidance', 'information'): the type of document
url	URL: the address of the document

when

object: details of when the policy applies

when

value('at_earliest_opportunity', 'on_completion', 'on_publication', 'unspecified'): when the policy applies

following_project_completion

object: how long after project completion the policy applies

amount	integer: amount
units	value('days', 'weeks', 'months', 'years')

policy_effective_data

object: the date the policy became effective

for_new_projects	date: date for new projects
for_existing_projects	date: date for existing projects
earlier_compliance_encouraged	value('yes','no'): whether earlier compliance is encouraged

special_conditions

array of text: Free-text conditions (things that don't fit easily into the data model)

access_cost

value('free_access', 'nonprofit_cost_recovery'):

funder_group

funder_group_metadata

object: core metadata for this funder group

Integer: the Sherpa ID for this item

name

array of objects: the name of the group

name	text: the name of the group
acronym	text: a short-form for the name
preferred	value('name', 'acronym'): which is preferred
language	value(two-letter language code): the language of this value

Note that this is a multilingual field and should only have one entry per language.

url

URL: the url of the funder group

country

value(two letter country code): the country of the funder group

description

text: description

notes

text: notes about the funder group record

funders

array of objects: the funders that are part of this group

id	integer: the Sherpa ID of the funder
name	text: the preferred name of the funder
uri	URL: the address within Sherpa of the funder
type	value('funder'): the object type

publisher

Integer: the Sherpa ID for this item

name

array of objects: the name of the publisher

name	text: the name of the publisher
acronym	text: a short-form for the name
preferred	value('name', 'acronym'): which is preferred
language	value(two-letter language code): the language of this value

Note that this is a multilingual field and should only have one entry per language.

url

URL: the url of the publisher

identifiers

array of objects: identifiers associated with this publisher

identifier	text: the identifier
type	value('ror', 'other'): the identifier type

country

value(two letter country code): the country of the publisher

notes

text: notes about the publisher record

imprint_of

publisher object: if the publisher is an imprint, which publisher is this an imprint of? Note that funder objects in this section will only include the following fields: id, name, url, country, notes, imprint_of_id, imprints_id, publication_count, uri

imprints

array of publisher object: imprints of this publisher. Note that funder objects in this section will only include the following fields: id, name, url, country, notes, imprint_of_id, imprints_id, publication_count, uri

policies

array of publisher_policy object: Note that publisher policy objects in this section will only include the following fields: id, internal_moniker, publication_count, permitted_oa, urls, open_access_prohibited, uri

publication_count

integer: the number of publication records in Sherpa for this publisher

publications

array of publication object: the publisher's publications. Note that publication objects in this section will only include the following fields: id, title, issns, type, uri

publisher_policy

integer: the ID of the object

internal_moniker

text: a name used internally by Sherpa's editorial team

urls

multiple object

url	URL: a policy url
description	text: description

open_access_prohibited

value('yes','no'): does the policy prohibit Open Access?

notes

text: notes about the policy

contributors

array of text: organisations and people that assisted with the curation of this policy record

publisher

publisher object: the publisher that owns this policy. Note that only the following fields are available here: id, name, url, country, notes, imprint_of_id, imprints_id, publication_count, uri

publication_count

integer: the number of publications this policy is attached to

publications

array of publication object: Note that only the following fields are available here: id, title, issns, type, uri

permitted_oa

array of objects: the OA this policy permits

integer: the Sherpa ID for this item

prerequisites

object

prerequisites	array of value( 'requires_publisher_permission', 'when_required_by_funder', 'when_required_by_law', 'when_required_by_institution', 'when_research_article'): prerequisites
prerequisite_funders	array of funder object: prerequisite funder. Note that only the following fields are available here: funder_metadata(id, name, url, country, description, notes, groups, identifiers), system_metadata(id, uri)
prerequisite_subjects	array of text: prerequisite subjects

article_version

array of value('submitted','accepted','published'): which article versions this applies to

location

object

location	array of value('academic_social_network', 'any_repository', 'any_website', 'authors_homepage', 'funder_designated_location', 'institutional_repository', 'institutional_website', 'named_academic_social_network', 'named_repository', 'non_commercial_institutional_repository', 'non_commercial_repository', 'non_commercial_social_network', 'non_commercial_subject_repository', 'non_commercial_website', 'preprint_repository', 'subject_repository', 'this_journal'): the place the article will be open access. Note that 'this_journal' refers to an Open Access Route provided by the journal itself (open-access publishing). When comparing a location against a policy, bear in mind that some values may match other, e.g.: an institutional_repository may be a non_commercial_repository if any_website is set, any location is permitted
named_repository	array of text: named repositories that are permitted. used if 'named_repository' is selected
named_academic_social_network	array of text: named social networks that are permitted. used if 'named_academic_social_network' is selected

embargo

object: the embargo required

amount	integer: amount
units	value('days', 'weeks', 'months', 'years')

copyright_owner

value('authors', 'authors_institution', 'journal', 'learned_society', 'publishers', 'shared_authors_and_journal', 'shared_authors_and_learned_society', 'shared_authors_and_publishers', 'shared_authors_and_authors_institution'): copyright owner

license

array of object

additional_oa_fee

value('yes','no'): is an additional fee required to enable this route

conditions

array of text: conditions

publisher_deposit

multiple repository object: the location(s) the publisher will automatically deposit the article into. Note that only the following fields are available here: repository_metadata(name, type, description, notes, url), system_metadata(id, uri)

public_notes

text: notes about this permitted_oa

workflow_dates

object

publisher_last_contacted	date: when the editorial team last contacted the publisher
policy_last_reviewed	date: when the editorial team last reviwed the policy

publication

integer: the Sherpa ID for this item

title

array of objects: the multilingual title of the item

title	text: the title of the publication
acronym	text: a short-form for the title
preferred	value('title', 'acronym'): which is preferred
language	value(two-letter language code): the language of this value

Note that this is a multilingual field and should only have one entry per language.

issns

array of object

type	value('print','electronic','legacy'): the type of the issn
issn	text: the issn of the publication

type

value('journal', 'conference_proceedings', 'monographic_series'): the type of the publication

notes

text: notes about the publication record

url

URL: the url of the publication

listed_in_doaj

value('yes','no'): is the publication listed in DOAJ

tj_status

array of values('plan_s_approved','jisc_approved'): set when a publication is a tranformative journal approved by Plan S and/or Jisc

publishers

array of publisher objects: the publishers of this journal. Note that only the following fields are available here: id, title, issns, type, uri

publisher_policy

array of publisher_policy_objects: the set of policies that together define what can OA is available for articles published in this publication. Note that publisher policy objects in this section will only include the following fields: id, internal_moniker, publication_count, permitted_oa, urls, open_access_prohibited, uri

repository

repository_metadata

object: core metadata for this repository

name

array of objects: the name of the repository

name	text: the name of the repository
acronym	text: a short-form for the name
preferred	value('name', 'acronym'): which is preferred
language	value(two-letter language code): the language of this value

Note that this is a multilingual field and should only have one entry per language.

type

value('undetermined', 'institutional', 'disciplinary', 'aggregating', 'governmental'): the type of repository

notes

text: additional information about the repository

url

URL: the url of the repository

oai_url

URL: the url of the primary OAI interface

software

object: the repository's software platform

content_types

array of values('journal_articles', 'bibliographic_references', 'conference_and_workshop_papers', 'theses_and_dissertations', 'unpub_reports_and_working_papers', 'books_chapters_and_sections', 'datasets', 'learning_objects', 'software', 'patents', 'other_special_item_types'): The types of items in the repository

content_subjects

integer: the content of the subjects

1	Multidisciplinary
2	Science General
3	Agriculture, Food and Veterinary
4	Biology and Biochemistry
5	Chemistry and Chemical Technology
6	Earth and Planetary Sciences
7	Ecology and Environment
8	Mathematics and Statistics
9	Physics and Astronomy
10	Health and Medicine
11	Technology General
12	Architecture
13	Civil Engineering
14	Computers and IT
15	Electrical and Electronic Engineering
16	Mechanical Engineering and Materials
17	Arts and Humanities General
18	Fine and Performing Arts
19	Geography and Regional Studies
20	History and Archaeology
21	Language and Literature
22	Philosophy and Religion
23	Social Sciences General
24	Business and Economics
25	Education
26	Law and Politics
27	Library and Information Science
28	Management and Planning
29	Psychology

Note that the content types may be reviewed in the future and are subject to change.

metadata_record_count

integer: the number of records in the repository (with or without a document attached)

full_text_record_count

integer: the number of records in the repository with a document attached

organisation

object: the organisation responsible for this repository

name

array of objects: the name of the organisation

name	text: the name of the organisation
acronym	text: a short-form for the name
preferred	value('name', 'acronym'): which is preferred
language	value(two-letter language code): the language of this value

Note that this is a multilingual field and should only have one entry per language.

url

URL: the url of the organisation

country

value(two letter country code): the country of the organisation

notes

text: organisation notes

policies

object: repository policies. Note that this section is currently under review and may change soon.