Health Research Data Catalogue API

Container object for all summary dataset resources that match the request.

The total number of resources that match the request.

Repeats all summary dataset resources (items) that match the request.

JSON Schema specification that summary dataset resource (item) conforms to.

JSON document type. The JSON dataset is a JSON document, which includes descriptive metadata.

Dataset schema URL resolves to version of conformant JSON schema.

Data set persistent identifier that is common across all data set revisions.

Data set name.

Data set description.

Data set version.

Self continuation link of a search result.

Data set metadata creation date.

Data set metadata modification date.

The source of the data set.

Outcome of an operation that does not result in a resource or bundle being returned, for example an error or an async/batch submission. There are a number of possible error codes that can be returned along with a more detailed description in the display field.

FHIR Resource Type.

List of issues that have occurred.

Severity of the error.

FHIR error code.

Internal error code.

URI of the coding system specification.

Version of the coding system in use.

Symbol in syntax defined by the system.

Representation defined by the system.

Additional diagnostic information about the issue. This information is subject to change.

HDR UK Dataset Metadata Schema.

System data set identifier (logical identifier of the dataset resource assigned by the Central Metastore). This is not the Dataset persistent identifier that is common across all dataset resource revisions.

Data set metadata version.

Data set Revisions. Includes the Semantic Version of the data set and URL endpoint to obtain the version.

Data set Metadata Creation Date.

Data set Metadata Modification Date.

Summary metadata must be completed by Data Custodians onboarding. metadata into the Innovation Gateway MVP.

Title of the data set limited to 80 characters. It should provide a short description of the data set and be unique across the gateway. The title can be prefixed with an organisation name or identifier to differentiate it from other data sets within the Gateway. Good titles should avoid acronyms, summarise the content of the data set and if relevant, the region the data set covers.

Data set Abstract provides a clear and brief descriptive signpost for researchers who are searching for data that may be relevant to their research. The abstract should allow the reader to determine the scope of the data collection and accurately summarise its content. The optimal length is one paragraph (limited to 255 characters) and effective abstracts should avoid long sentences and abbreviations where possible.

Data set publisher is the organisation responsible for running or supporting the data access request process, as well as publishing and maintaining the metadata. In most this will be the same as the HDR UK Organisation (Hub or Alliance Member). However, in some cases this will be different i.e. Tissue Directory are an HDR UK Gateway organisation but coordinate activities across a number of data publishers i.e. Cambridge Blood and Stem Cell Biobank.

Organisation metadata describes an organisation for purposes of discovery and identification.

Provides a Grid.ac identifier (see https://www.grid.ac/institutes) for your organisation. If an organisation does not have a Grid.ac identifier use the “suggest and institute” function here: https://www.grid.ac/institutes#

Name of the organisation.

Provides a logo associated with the Gateway Organisation using a valid URL. The following formats will be accepted .jpg, .png or .svg.

Provides a URL that describes the organisation.

Organisation contact point(s).

Indicates if the organisation is an Alliance Member or a Hub.

The URL of a webpage where the data access request process and/or guidance is provided. Can support multiple access processes i.e. industry vs academic.

Provides an indication of the typical processing times based on the types of requests typically received. Note: This value will be used as default access request duration for all data sets submitted by the organisation. However, there will be the opportunity to overwrite this value for each data set.

Provides a brief description of the data access services that are available including: environment that is currently available to researchers;additional consultancy and services;any indication of costs associated. If no environment is currently available, indicate the current plans and timelines when and how data will be made available to researchers Note: This value will be used as default access environment for all data sets submitted by the organisation. However, there will be the opportunity to overwrite this value for each data set.

Provides link(s) to a webpage or a short description detailing the commercial model for processing data access requests for the organisation (if available) Definition: Indication of commercial model or cost (in GBP) for processing each data access request by the data custodian.

Provides an indication of consent permissions for data sets and/or materials, and relates to the purposes for which data sets and/or material might be removed, stored or used. Notes: where there are existing data-sharing arrangements such as the HDR UK HUB data sharing agreement or the NIHR HIC data sharing agreement this should be indicated within access rights. This value will be used as terms for all data sets submitted by the organisation. However, there will be the opportunity to overwrite this value for each data set.

Indicates if there are any additional conditions set for use if any, multiple requirements may be provided. Ensure that these restrictions are documented in access rights information.

Provides a valid email address that can be used to coordinate data access requests with the publisher. Organisations are expected to provide a dedicated email address associated with the data access request process. Notes: An employee’s email address can only be provided on a temporary basis and if one is provided an explicit consent must be obtained for this purpose.

Provides relevant and specific keywords that can improve the SEO of your data set as a comma separated list. Notes: Onboarding portal will suggest keywords based on title, abstract and description. We are compiling a standardised list of keywords and synonyms across data sets to make filtering easier for users.

Alternate data set identifiers or local identifiers.

All HDR UK registered data sets should either have a Digital Object Identifier (DOI) or be working towards obtaining one.

Documentation can include a rich text description of the data set or links to media such as documents, images, presentations, videos or links to data dictionaries, profiles or dashboards. Organisations are required to confirm that they have permission to distribute any additional media.

A free-text description of the record.

Provides any media associated with the Gateway Organisation using a valid URI for the content. This is an opportunity to provide additional context that could be useful for researchers wanting to understand more about the data set and its relevance to their research question. The following formats will be accepted .jpg, .png or .svg, .pdf, .xslx or .docx. Note: media asset can be hosted by the organisation or uploaded using the onboarding portal.

Indicates if the data set is part of a group or family.

Coverage information includes attributes for geographical and temporal coverage, cohort details etc. to enable a deeper understanding of the data set content so that researchers can make decisions about the relevance of the underlying data.

The geographical area covered by the data set. It is recommended that links are to entries in a well-maintained gazetteer such as https://www.geonames.org/ or https://what3words.com/daring.lion.race.

Indicates the age range in whole years of participants in the data set. Range has the following format ‘[min age] – [max age]’ where both the minimum and maximum are whole numbers (integers).

Availability of physical samples associated with the data set. Indicates the types of samples that are avilable. More than one type may be provided. If sample are not yet available, use “AVAILABILITY TO BE CONFIRMED”. If samples are not available, use “NOT AVAILABLE”.

If known, what is the typical time span that a patient appears in the data set (follow up period).

Indicates if the data set is representative of the patient pathway and any limitations the data set may have with respect to pathway coverage. This could include if the data set is from a single speciality or area, a single tier of care, linked across two tiers (e.g. primary and secondary care), or an integrated care record covering the whole patient pathway.

Provenance information allows researchers to understand data within the context of its origins and can be an indicator of quality, authenticity and timeliness.

Indicates the purpose(s) that the data set was collected.

Indicates the source of the data extraction.

Indicates the setting(s) where data was collected. Multiple settings may be provided.

Indicates the frequency of distribution release. If a data set is distributed regularly then a distribution release periodicity from the constrained list should be used which indicates the next release date. When the release date becomes historical, a new release date will be calculated based on the publishing periodicity. If a data set has been published and will remain static indicate that it is static and indicate when it was released. If a data set is released on an irregular basis or “on-demand” indicate that it is Irregular and leave release date as null. If a data set can be published in real-time or near-real-time indicate that it is continuous and leave release date as null. Notes: see https://www.dublincore.org/specifications/dublin-core/collection-description/frequency/.

Date of the latest release of the data set. If this is a regular release i.e. quarterly, or this is a static data set this should be completed alongside Periodicity. If this is Irregular or Continuously released leave this blank. Notes: Periodicity and release date will be used to determine when the next release is expected. E.g. if the release date is documented as 01/01/2020 and it is now 20/04/2020 and there is a quarterly release schedule, the latest release will be calculated as 01/04/2020.

The start of the time period that the data set provides coverage for. If there are multiple cohorts in the data set with varying start dates, provide the earliest date and use the description or the media attribute to provide more information.

The end of the time period that the data set provides coverage for. If the data set is “Continuous” and has no known end date, state continuous. If there are multiple cohorts in the data set with varying end dates, provide the latest date and use the description or the media attribute to provide more information.

Indicates the typical time-lag between an event and the data for that event appearing in the data set.

Accessibility information allows researchers to understand access, usage, limitations, formats, standards and linkage or interoperability with toolsets.

This section includes information about how the data can be used and how it is currently being used.

Provides an indication of consent permissions for data sets and/or materials, and relates to the purposes for which data sets and/or material might be removed, stored or used. NOTE: we have extended the DUO to include a value for NO LINKAGE.

Indicates if there are any additional conditions set for use if any, multiple requirements may be provided. These restrictions are documented in access rights information.

Provides the text that you would like included as part of any citation that credits this data set. This is typically just the name of the publisher. No employee details should be provided.

Investigations.

Provides the keystone paper associated with the data set. Also include a list of known citations, if available and should be links to existing resources where the data set has been used or referenced. Provides multiple entries, or if a csv upload provides them as a tab separated list.

This section includes information about data access.

Access rights.

Provides a brief description of the data access services that are available including: environment that is currently available to researchers;additional consultancy and services;any indication of costs associated. If no environment is currently available, indicates the current plans and timelines when and how data will be made available to researchers Note: This value will be used as default access environment for all data sets submitted by the organisation. However, there will be the opportunity to overwrite this value for each data set.

Provides link(s) to a webpage detailing the commercial model for processing data access requests for the organisation (if available) Definition: Indication of commercial model or cost (in GBP) for processing each data access request by the data custodian.

Provides an indication of the typical processing times based on the types of requests typically received.

Country code from ISO 3166-1 country codes and the associated ISO 3166-2 for regions, cities, states etc. for the country/state under whose laws the data subjects’ data is collected, processed and stored.

Data Controller means a person/entity who (either alone or jointly or in common with other persons/entities) determines the purposes for which and the way any Data Subject data, specifically personal data or are to be processed.

A Data Processor, in relation to any Data Subject data, specifically personal data, means any person/entity (other than an employee of the data controller) who processes the data on behalf of the data controller.

Section includes technical attributes for language vocabularies, sizes etc. and gives researchers facts about and processing the underlying data in the data set.

Lists any relevant terminologies / ontologies / controlled vocabularies, such as ICD 10 Codes, NHS Data Dictionary National Codes or SNOMED CT International, that are being used by the data set. If the controlled vocabularies are local standards, make that explicit. If you are using a standard that has not been included in the list, use “other” and contact support desk to ask for an addition. Notes: More than one vocabulary may be provided.

Lists standardised data models that the data set has been stored in or transformed to, such as OMOP or FHIR. If the data is only available in a local format, make that explicit. If you are using a standard that has not been included in the list, use “other” and contact support desk to ask for an addition.

This should list all the languages in which the data set metadata and underlying data is made available.

If multiple formats are available specify. See application, audio, image, message, model, multipart, text, video, https://www.iana.org/assignments/media-types/media-types.xhtml Note: If your file format is not included in the current list of formats, indicate other. If you are using the HOP you will be directed to a service desk page where you can request your additional format. If not go to: https://metadata.atlassian.net/servicedesk/customer/portal/4 to request your format.

Enrichment and Linkage includes information about related data sets that may have previously been linked, as well as indicating if there is the opportunity to link to other data sets in the future. If a data set has been enriched and/or derivations, scores and existing tools are available this section allows providers to indicate this to researchers.

If applicable, provides the DOI of other data sets that have previously been linked to this data set and their availability. If no DOI is available, provides the title of the data sets that can be linked, where possible using the same title of a data set previously onboarded to the HOP. Note: If all the data sets from Gateway organisation can be linked indicate “ALL” and the onboarding portal will automate linkage across the data sets submitted.

Indicate if derived data sets or predefined extracts are available and the type of derivation available. Notes. Single or multiple dimensions can be provided as a derived extract alongside the data set.

Provides the URL of any analysis tools or models that have been created for this data set and are available for further use. Multiple tools may be provided. Note: We encourage users to adopt a model along the lines of https://www.ga4gh.org/news/tool-registry-service-api-enabling-an-interoperable-library-of-genomics-analysis-tools/.

Multiple observations about the data set may be provided and users are expected to provide at least one observation (1..*). We will be supporting the schema.org observation model (https://schema.org/Observation) with default values. Users will be encouraged to provide their own statistical populations as the project progresses. Examples:

Supports statistical populations codes for an observation.

Provides the population size associated with the population type the data set i.e. 1000 people in a study, or 87 images (MRI) of Knee Usage Note: Used with Statistical Population, which specifies the type of the population in the data set.

If SNOMED CT term does not provide sufficient detail, this field provides a description that disambiguates the population type.

Provides the date that the observation was made. Some data sets may be continuously updated and the number of records will change regularly, so the observation date provides users with the date that the analysis or query was run to generate the particular observation. Multiple observations can be made i.e. an observation of cumulative COVID positive cases by specimen on the 1/1/2021 could be 2M. On the 8/1/2021 a new observation could be 2.1M. Users can add multiple observations.

Initially this will be defaulted to "COUNT".

Outcome of an operation that does not result in a resource or bundle being returned, for example an error or an async/batch submission. There are a number of possible error codes that can be returned along with a more detailed description in the display field.

FHIR Resource Type.

List of issues that have occurred.

Severity of the error.

FHIR error code.

Internal error code.

URI of the coding system specification.

Version of the coding system in use.

Symbol in syntax defined by the system.

Representation defined by the system.

Additional diagnostic information about the issue. This information is subject to change.