JSON Schema for Studies

From ECRIN-MDR Wiki
Revision as of 15:06, 7 October 2021 by Admin (talk | contribs)
Jump to navigation Jump to search

The current (version 6) form of the JSON schema for the Study file is shown below.
This version was created in August 2021.

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "$id": "http://ecrin.org/json_schemas/mdrstudy/v6.json",
    "title": "Study definition",
    "description": "ECRIN Metadata Repository for clinical research objects, Study JSON definition, version 6 August 2021",
    "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_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 one exists"
                   },
                   "mesh_value": {
                       "type": "string",
                       "description": "The topic or keyword value or name, as a MESH term if coded, otherwise as provided in the source data"
                   },
                   "original_value": {
                       "type": "string",
                       "description": "The original value of the term, whether coded or not"
                   }
               }
            }
        },


        "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"
                    }
                }
            }
        },

        "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"
        }
    }
}