JSON Schema for Studies
Jump to navigation
Jump to search
Last updated: 20/09/2022
The current (version 7.1) form of the JSON schema for the Study file is shown below.
This version was created in November 2022.
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "http://ecrin.org/json_schemas/mdrstudy/v7.1.json",
"title": "Study definition",
"description": "ECRIN Metadata Repository for clinical research objects, Study JSON definition, version 7.1 November 2022",
"type": "object",
"required": ["id", "display_title"],
"additionalProperties": false,
"properties": {
"file_type": {
"type": "string",
"description": "always 'study'"
},
"id": {
"type": "integer",
"description": "Internal accession number of the study within the MDR database"
},
"display_title": {
"type": "string",
"description": "By default the public or brief study title. If that is missing then the full scientific title"
},
"brief_description": {
"type": "string",
"description": "Brief description, usually a few lines, of the study. For some sources may need to be derived from key study features."
},
"data_sharing_statement": {
"type": "string",
"description": "A statement from the sponsor and / or study leads about their intentions for IPD sharing (may be structured in some sources)."
},
"study_type": {
"type": "object",
"description": "Categorisation of study type, e.g. 'Interventional', or 'Observational'",
"properties": {
"id": {
"type": "integer",
"description": "An integer referencing the relevant record in the study_types enumeration / lookup table"
},
"name": {
"type": "string",
"description": "One of the types listed in the study_types enumeration"
}
}
},
"study_status": {
"type": "object",
"description": "Categorisation of study status, e.g. 'Active, not recruiting', or 'Completed'",
"properties": {
"id": {
"type": "integer",
"description": "An integer referencing the relevant record in the study_statuses enumeration / lookup table"
},
"name": {
"type": "string",
"description": "One of the statuses listed in the study_statuses enumeration"
}
}
},
"study_enrolment": {
"type": "string",
"description": "The anticipated or actual total number of participants in the clinical study. Usually a number but may be a more detailed descriptive phrase"
},
"study_gender_elig": {
"type": "object",
"description": "Whether the study is open to all genders, or just male or female",
"properties": {
"id": {
"type": "integer",
"description": "An integer referencing the relevant record in the gender_eligibility_types enumeration / lookup table"
},
"name": {
"type": "string",
"description": "One of the types from the gender_eligibility_types enumeration"
}
}
},
"min_age": {
"type": "object",
"description": "The minimum age, if any, for a study participant",
"properties": {
"value": {
"type": "integer",
"description": "The numerical value of the age"
},
"unit_id": {
"type": "integer",
"description": "An integer referencing the relevant record in the time_units enumeration / lookup table"
},
"unit_name": {
"type": "string",
"description": "One of the allowed types, from the time_units enumeration, e.g. 'Months', or 'Years'"
}
}
},
"max_age": {
"type": "object",
"description": "The maximum age, if any, for a study participant",
"properties": {
"value": {
"type": "integer",
"description": "The numerical value of the age"
},
"unit_id": {
"type": "integer",
"description": "An integer referencing the relevant record in the time_units enumeration / lookup table"
},
"unit_name": {
"type": "string",
"description": "One of the allowed types, from the time_units enumeration, e.g. 'Months', or 'Years'"
}
}
},
"study_start_time": {
"type": "object",
"description": "The year and month the study began (usually first patient first visit)",
"properties": {
"year": {
"type": "integer",
"description": "A 4-digit integer referencing the start year"
},
"month": {
"type": "integer",
"description": "An integer from 1 to 12 referencing the start month, if known"
}
}
},
"study_identifiers": {
"type": "array",
"items": {
"type": "object",
"description": "A composite object that indicates the value and type of the identifier, and optionally its date and organisation of origin",
"required": ["id", "value", "type"],
"properties": {
"id": {
"type": "integer",
"description": "Study identifier record primary key, generated automatically in database"
},
"identifier_value": {
"type": "string",
"description": "The identifier value, in a standardised format (for each identifier type)"
},
"identifier_type": {
"type": "object",
"description": "The category of the identifier, e.g. 'Trial Registry ID', or 'Sponsor ID'",
"properties": {
"id": {
"type": "integer",
"description": "An integer referencing the relevant record in the identifier_types enumeration / lookup table"
},
"name": {
"type": "string",
"description": "One of the types in the identifier_types enumeration."
}
}
},
"identifier_org": {
"type": "object",
"description": "The organisation providing the identifier",
"properties": {
"id": {
"type": "integer",
"description": "The id of the organisation within the ECRIN context database, if that id exists"
},
"name": {
"type": "string",
"description": "The default name of the organisation within the ECRIN context database, if it exists, or the name of the organisation as supplied by the source data"
},
"ror_id": {
"type": "string",
"description": "The id of the organisation, if known, within the ROR (Research Organisation Registry) system. This is a URL linking to the ROR resource."
}
}
},
"identifier_date": {
"type": "string",
"description": "The date the identifier was allocated, if known, in a string 'yyyy MMM dd' format, e.g. '2015 Dec 12'"
},
"identifier_link": {
"type": "string",
"description": "Any URL associated with the identifier"
}
}
}
},
"study_titles": {
"type": "array",
"items": {
"type": "object",
"description": "A composite object that indicates the type and value of any study title",
"required": ["id", "title_type", "title_text"],
"properties": {
"id": {
"type": "integer",
"description": "study title record primary key, generated automatically in database"
},
"title_type": {
"type": "object",
"description": "Type of the title, e.g. 'Abbreviation or Acronym', or 'Translated Title'",
"properties": {
"id": {
"type": "integer",
"description": "An integer referencing the relevant record in the title_types enumeration / lookup table"
},
"name": {
"type": "string",
"description": "One of the types listed in the title_types enumeration"
}
}
},
"title_text": {
"type": "string",
"description": "The text of the title, verbatim"
},
"lang_code": {
"type": "string",
"description": "A two letter ISO 369-1 code indicating the language of the title"
},
"comments": {
"type": "string",
"description": "Usually indicates the source of the title, to make later comparisons easier."
}
}
}
},
"study_features": {
"type": "array",
"items": {
"type": "object",
"description": "A composite object that indicates the type and value of any study feature - usually a design feature, often used for filtering",
"required": ["id"],
"properties": {
"id": {
"type": "integer",
"description": "Study feature record primary key, generated automatically in database"
},
"feature_type": {
"type": "object",
"description": "The type of study feature, e.g. 'Phase', or 'Masking'",
"properties": {
"id": {
"type": "integer",
"description": "An integer referencing the relevant record in the study_feature_types enumeration / lookup table"
},
"name": {
"type": "string",
"description": "One of the features listed in the study_feature_types enumeration"
}
}
},
"feature_value": {
"type": "object",
"description": "The value of the feature, as taken from a pre-defined list, e.g. 'Phase 3', or 'Double'",
"properties": {
"id": {
"type": "integer",
"description": "An integer referencing the relevant record in the study_feature_categories enumeration / lookup table"
},
"name": {
"type": "string",
"description": "One of the allowed values listed in the relevant part of the study_feature_categories enumeration"
}
}
}
}
}
},
"study_topics": {
"type": "array",
"items": {
"type": "object",
"description": "A composite object that indicates the topic name or keyword, and - where available - the MESH coding for that term",
"required": ["id", "value"],
"properties": {
"id": {
"type": "integer",
"description": "Study topic record primary key, generated automatically in database"
},
"topic_type": {
"type": "object",
"description": "How the topic was categorised in the source data, e.g. 'Condition', or 'Organism'",
"properties": {
"id": {
"type": "integer",
"description": "An integer referencing the relevant record in the topic_source_types enumeration / lookup table"
},
"name": {
"type": "string",
"description": "One of the allowed types listed in the topic_source_types enumeration"
}
}
},
"mesh_coded": {
"type": "boolean",
"description": "Whether or not the topic has been MESH coded"
},
"mesh_code": {
"type": "string",
"description": "The MESH code for the topic, if coding to MESH has been possible or was already present in the source data"
},
"mesh_value": {
"type": "string",
"description": "The MESH term for the topic or keyword, if coding to MESH has been possible or was already present in the source data"
},
"ct_type": {
"type": "object",
"description": "The controlled terminology system (if any) used for the topic term in the source data",
"properties": {
"id": {
"type": "integer",
"description": "An integer referencing the relevant record in the topic_vocabularies enumeration / lookup table"
},
"name": {
"type": "string",
"description": "One of the allowed types listed in the topic_vocabularies enumeration"
}
}
},
"ct_code": {
"type": "string",
"description": "The original code used for the topic or keyword, if a controlled terminology was used in the source data"
},
"original_value": {
"type": "string",
"description": "The original value of the term, whether coded or not"
}
}
}
},
"study_contributors": {
"type": "array",
"items": {
"type": "object",
"description": "A composite object that indicates the people and / or organisations that contributed to the study",
"required": ["id", "contribution_type"],
"properties": {
"id": {
"type": "integer",
"description": "Study contributor record primary key, generated automatically in database"
},
"contribution_type": {
"type": "object",
"description": "The type of contribution made, by an individual or organisation, e.g., 'Study Lead', or 'Trial Sponsor'",
"properties": {
"id": {
"type": "integer",
"description": "An integer referencing the relevant record in the contribution_types enumeration / lookup table"
},
"name": {
"type": "string",
"description": "One of the allowed types in the contribution_types enumeration"
}
}
},
"is_individual": {
"type": "boolean",
"description": "Indicates whether the contributor is an individual, e.g. study lead or paper author, or an organisation, e.g. pharma company or research network.
If an organisation the person object will be null. If a person, the organisation object will be null."
},
"organisation": {
"type": "object",
"description": "The organisation providing the contribution - not required if the contributor is an individual.",
"properties": {
"id": {
"type": "integer",
"description": "The id of the organisation, within the ECRIN context database, if that id exists"
},
"name": {
"type": "string",
"description": "The default name of the organisation, within the ECRIN context database, if it exists, or the name of the organisation as supplied by the source data"
},
"ror_id": {
"type": "string",
"description": "The id of the organisation, if known, within the ROR (Research Organisation Registry) system. This is a URL linking to the ROR resource."
}
}
},
"person": {
"type": "object",
"description": "A composite object that should include as a minimum a full_name. Not required if there is an organisation entry",
"properties": {
"family_name": {
"type": "string",
"description": "The person's family name, the 'key' name under which they are listed - usually the last name in Western cultures"
},
"given_name": {
"type": "string",
"description": "The person's given name, or the first name by which they are nornally known. May be replaced by initials"
},
"full_name": {
"type": "string",
"description": "The person's full name, in the order of given_name family_name"
},
"orcid": {
"type": "string",
"description": "The person's ORCID identifier, if known"
},
"affiliation_string": {
"type": "string",
"description": "The person's organisational affiliation as it appears in the source data"
},
"affiliation_org_id": {
"type": "integer",
"description": "The id of the organisation within the MDR, if it can be identified from the affiliation string."
},
"affiliation_org_name": {
"type": "string",
"description": "The name of the organisation to which the person is affiliated, as deduced from the affiliation string."
},
"affiliation_org_ror_id": {
"type": "string",
"description": "The id of the organisation to which the person is affiliated, if known, within the ROR (Research Organisation Registry) system. This is a URL linking to the ROR resource."
}
}
}
}
}
},
"study_relationships": {
"type": "array",
"items": {
"type": "object",
"description": "A composite object that indicates any related study and the nature of the relationship",
"required": ["id", "relationship_type", "target_study_id"],
"properties": {
"id": {
"type": "integer",
"description": "Study relationships record primary key, generated automatically in database"
},
"relationship_type": {
"type": "object",
"description": "The nature of the relationship, e.g. 'Is a sub-study of', or 'has an expanded access version",
"properties": {
"id": {
"type": "integer",
"description": "An integer referencing the relevant record in the study_relationship_types enumeration / lookup table"
},
"name": {
"type": "string",
"description": "One of the allowed types from the study_relationship_types enumeration"
}
}
},
"target_study_id": {
"type": "integer",
"description": "The id, i.e. internal accession number, of the related study"
}
}
}
},
"study_countries": {
"type": "array",
"items": {
"type": "object",
"description": "A composite object that indicates the country or countries where study participants were recruited",
"required": ["id", "country"],
"properties": {
"id": {
"type": "integer",
"description": "Study country record primary key, generated automatically in database"
},
"country": {
"type": "object",
"description": "A country of recruitment, as identified by its Geonames id and name",
"properties": {
"geonames_id": {
"type": "integer",
"description": "An integer referencing the Geonames geographical database system, (if the source data matches a recognised country)"
},
"name": {
"type": "string",
"description": "The name of the country, in the Geonames system (or if unmatched the name as originally provided)"
}
}
},
"status": {
"type": "object",
"description": "The recruitment or activity status of the country, as of the most recent data harvest",
"properties": {
"id": {
"type": "integer",
"description": "An integer referencing the relevant record in the study_status_types enumeration / lookup table"
},
"name": {
"type": "string",
"description": "One of the allowed types from the study_status_types enumeration"
}
}
}
}
}
},
"study_sites": {
"type": "array",
"items": {
"type": "object",
"description": "A composite object that indicates the clinical sites participating in the study",
"required": ["id", "facility"],
"properties": {
"id": {
"type": "integer",
"description": "Study sites record primary key, generated automatically in database"
},
"facility": {
"type": "object",
"description": "The clinical facility acting as a study site",
"properties": {
"id": {
"type": "integer",
"description": "The id of the organisation within the ECRIN context database, if that id exists"
},
"name": {
"type": "string",
"description": "The default name of the organisation within the ECRIN context database, if it exists, or the name of the organisation as supplied by the source data"
},
"ror_id": {
"type": "string",
"description": "The id of the organisation, if known, within the ROR (Research Organisation Registry) system. This is a URL linking to the ROR resource."
}
}
},
"city": {
"type": "object",
"description": "The city in which the facility is found, as identified by its Geonames id and name",
"properties": {
"geonames_id": {
"type": "integer",
"description": "An integer referencing the Geonames geographical database system, if the source data name can be matched to a listed city name"
},
"name": {
"type": "string",
"description": "The name of the city, as in the Geonames system (or if unmatched the name as originally provided)"
}
}
},
"country": {
"type": "object",
"description": "The country in which the facility is found, as identified by its Geonames id and name",
"properties": {
"geonames_id": {
"type": "integer",
"description": "An integer referencing the Geonames geographical database system, (if the source data matches a recognised country)"
},
"name": {
"type": "string",
"description": "The name of the country, in the Geonames system (or if unmatched the name as originally provided)"
}
}
}
"status": {
"type": "object",
"description": "The recruitment or activity status of the site, as of the most recent data harvest",
"properties": {
"id": {
"type": "integer",
"description": "An integer referencing the relevant record in the study_status_types enumeration / lookup table"
},
"name": {
"type": "string",
"description": "One of the allowed types from the study_status_types enumeration"
}
}
}
}
}
},
"linked_data_objects": {
"type": "array",
"items": {
"type": "integer",
"description": "The id, i.e. internal accession number, of the linked data object"
}
},
"provenance_string": {
"type": "string",
"description": "A listing of the source or sources (usually a trial registry) from which the data for the study has been drawn, and the date-time(s) when the data was last downloaded"
}
}
}
