Study JSON v3

The current (version 3) form of the JSON schema for the Study file is shown below.
This version was created in November 2019.

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "$id": "http://ecrin.org/json_schemas/mdrstudy/v3.json",
    "title": "XDC Study definition",
    "description": "ECRIN Metadata Repository for clinical research objects, Study JSON definition, version 3 November 2019",

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

        "display_title": {
            "type": "object",
            "properties": {
                "title": {
                    "type": "string",
                    "description": "By default the public or brief study title. If that is missing then the full scientific title, as used on the protocol document"
                },
                "lang_code": {
                    "$ref": "#/definitions/lang_code"
                }
            }
        },

        "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",
                        "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 allowed types, from the identifier_types enumeration, e.g. 'Trial Registry ID', or 'Sponsor ID'"
                            }
                        }
                    },

                    "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": "URL associated with the identifier"
                    },

                    "identifier_org": {
                        "$ref": "#/definitions/organisation"
                    }
                }
            }
        },

        "study_topics": {
            "type": "array",
            "items": {
                "type": "object",
                "description": "A composite object that indicates the topic name or keyword, and - if applicable - how it was classified in the source data, the controlled terminology system used, and the code for the topic in that system",
                "required": ["id", "value"],
                "properties": {
                    "id": {
                        "type": "integer",
                        "description": "Study topic record primary key, generated automatically in database"
                    },
                    "topic_value": {
                        "type": "string",
                        "description": "The topic or keyword value or name, as provided in the source data"
                    },
                    "topic_source_type": {
                        "type": "object",
                        "description": "How the topic was categorised in the source data, (or by using the controlled terminology, or using a category matching service)",
                        "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, from the topic_source_types enumeration, e.g. 'Condition', or 'Organism'"
                            }
                        }
                    },
                    "topic_ct": {
                        "type": "object",
                        "description": "If applicable, the controlled terminology system from which the topic name was taken",
                        "properties": {
                            "id": {
                                "type": "integer",
                                "description": "An integer referencing the relevant record in the topic_controlled_terminologies enumeration / lookup table"
                            },
                            "name": {
                               "type": "string",
                               "description": "One of the allowed types, from the topic_controlled_terminologies enumeration, e.g. 'MESH', or 'Cochrane PICO terminology'"
                            }
                        }
                    },
                    "topic_ct_code": {
                        "type": "string",
                        "description": "The code for the topic within the designated controlled terminology scheme"
                    }
                }
            }
        },

        "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",
                        "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 allowed types, from the title_types enumeration, e.g. 'Abbreviation or Acronym', or 'Translated Title'"
                            }
                        }
                    },

                    "title_text": {
                        "type": "string"
                    },

                    "lang_code": {
                        "$ref": "#/definitions/lang_code"
                    },

                    "contains_html": {
                        "type": "boolean"
                        "description": "Whether the title text has any embedded html tags, e.g. for super or subscripts" 
                    },

                    "comments": {
                        "type": "string"
                    }
                }
            }
        },

        "study_type": {
            "type": "object",
            "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 allowed types, from the study_types enumeration, e.g. 'Interventional', or 'Observational'"
                }
            }
        },

        "study_status": {
            "type": "object",
            "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 allowed types, from the study_statuses enumeration, e.g. 'Active, not recruiting', or 'Completed'"
                }
            }
        },

        "brief_description": {
            "type": "string",
            "description": "Brief description, usually a few lines, of the study"
        },

        "data_sharing_statement": {
            "type": "string",
            "description": "A statement from the sponsor and / or study leads about their intentions for IPD sharing"
        },

        "related_studies": {
            "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",
                        "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, e.g. 'Is a sub-study of', or 'has an expanded access version'"
                            }
                        }
                    },
                    "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"
            }
        }
    },

    "definitions": {

        "lang_code": {
            "type": "string",
            "minLength": 2,
            "maxLength": 2,
            "description": "A two letter ISO 369-1 code indicating the language of the study",
            "default": "en"
        },

        "organisation": {
            "type": "object",
            "required": ["name"],
            "properties": {
                "id": {
                    "type": "integer",
                    "description": "The id of the organisation within the ECRIN contextual database, if that id exists"
                },
                "name": {
                    "type": "array",
                    "description": "Either the name of the organisation as supplied by the source data, or the names (may be multiple) of the organisation within the ECRIN contextual database",
                    "minItems": 1,
                    "items": {
                        "type": "string"
                    }
                }
            }
        }
    }
}