EGA.assay.json

{
    "$schema": "https://json-schema.org/draft/2019-09/schema",
    "$id": "https://raw.githubusercontent.com/EbiEga/ega-metadata-schema/main/schemas/EGA.assay.json",
    "type": "object",
    "title": "EGA assay metadata schema",
    "meta:version": "0.0.0",
    "$async": true,
    "description": "Metadata schema used by the European Genome-phenome Archive (EGA) to validate its assay metadata object. This object is intended to contain metadata about the raw qualitative or quantitative test performed to determine any kind of biological property of a biological sample. It can be of different types: (1) sequencing assay [EFO:0003740] (e.g. sequence CRAM or FastQ files); and an (2) array assay [EFO:0002696] (e.g. intensity CEL files). Further details can be found in the EGA-metadata-schema GitHub repository (https://github.com/EbiEga/ega-metadata-schema/tree/main/schemas) and EGA-archive website (https://ega-archive.org/)",
    "required": ["objectId", "assayTypeSpecifications", "assayFiles"],
    "additionalProperties": false,
    "properties": {
      "objectId": {
        "type": "object",
        "title": "Object's IDs block",
        "description": "Node containing the main identifiers of the object (e.g. alias, centerName...), inherited from the common definitions. #! We extend the core object (objectCoreId) by adding a pattern check based on this schema's nature: an assay (by using EGAAssayIdPattern)", 
        "allOf": [
          {
            "title": "Inherited objectCoreId object",
            "$ref": "./EGA.common-definitions.json#/$defs/objectCoreId"
          },
          {
            "title": "Check that assay's EGA ID (EGAR) is correct",
            "properties": {
              "egaAccession": {
                "$ref": "./EGA.common-definitions.json#/$defs/EGAAssayIdPattern"
              }
            }
          }
        ]        
      },

      "schemaDescriptor": {
        "title": "Schema descriptor node",
        "description": "Inherited schema descriptor node containing metadata about the schemas and standards used to create the JSON document itself.",
        "$ref": "./EGA.common-definitions.json#/$defs/schemaDescriptor"
      },

      "objectTitle": {
        "type": "string",
        "title": "Title of the assay",
        "description": "An informative assay title that should serve as an overview of the assay and differentiate it from others. This short text can be used to call out assay records in searches or in displays.",
        "minLength": 1,
        "examples": [ "Ilumina sequencing assay 3409 - Cancer genomics" ]
      },

      "objectDescription": {
        "type": "string",
        "title": "Description of the assay",
        "description": "An in-depth description (e.g. used technology, sample groups, purpose...) of the assay. ",
        "minLength": 1,
        "examples": [ "Sequencing assay number 3409 of 4000. Sequenced through Illumina MiSeq to find SNPs of colorectal cancer samples..." ]
      },

      "assayCenter": {
        "type": "string",
        "title": "Centername that performed the assay",
        "description": "The name of the center (e.g. 'EBI-TEST') responsible for performing assay, if applicable, in case it's different from the center submitting metadata).",
        "minLength": 1,
        "examples": [ "EBI-TEST" ]
      },

      "assayDate": {
        "type": "string",
        "title": "Date of the assay",
        "description": "Date when the sequencing assay took place (e.g. '2021-05-15'). If the protocols are too long, the date shall be the day the assay concluded.",
        "format": "date",
        "examples": [ "2021-04-30", "2020-12-29" ]
      },

      "assayTypeSpecifications": {
        "type": "object",
        "title": "Assay type specifications",
        "description": "Node containing different sets of fields that depend on the instrument used for the assay: either array assays (those in which an [array instrument [EFO:0002698]](http://www.ebi.ac.uk/efo/EFO_0002698) was used) or sequencing assays (those in which a [sequencing instrument [EFO:0003739]](http://www.ebi.ac.uk/efo/EFO_0003739) was used). Depending on the used technology, different types of fields will be required. For example, if an array was used, its arraySampleLabels will be expected. Having this modular assay type-related node allows for easy additions of new technology-specific requirements.",
        "additionalProperties": false,
        "required": ["assayInstrument"],
        "properties": {
          "assayInstrument": {
            "type": "string",
            "title": "Assay type",
            "description": "The general categories, either sequencing or array, in which assays are categorized based on the used instruments. Term chosen from a list of controlled vocabulary (CV). If you cannot find your term in the CV list, please create an issue at our [metadata GitHub repository](https://github.com/EbiEga/ega-metadata-schema/issues/new/choose) proposing its addition.",
            "enum": ["array", "sequencer"],
            "meta:enum": {
              "array": "An assay in which an [array instrument [EFO:0002698]](http://www.ebi.ac.uk/efo/EFO_0002698) was used.",
              "sequencer": "An assay in which a [sequencer instrument [EFO:0003739]](http://www.ebi.ac.uk/efo/EFO_0003739) was used."
            }
          },
          "arrayAssaySpecifications": {
            "type": "object",
            "title": "Specifications of an array assay",
            "description": "Node containing the set of fields specific to an assay of type 'array' (i.e. an array was used to obtain the raw data).",
            "additionalProperties": false,
            "required": ["nLabelsPerArray"],
            "properties": {
              "nLabelsPerArray": {
                "type": "number",
                "title": "Number of labels per array",
                "description": "A single array can be prepared with biological materials labelled differently for them to be compared in parallel. Here one shall specify the number of labels used in the single array (e.g. 2 for a Two-colour cDNA microarray). Term chosen from a list of controlled vocabulary (CV). If you cannot find your term in the CV list, please create an issue at our [metadata GitHub repository](https://github.com/EbiEga/ega-metadata-schema/issues/new/choose) proposing its addition.",
                "enum": [1, 2, 3, 4],
                "meta:enum": {
                  "1": "One single label was used for a single array",
                  "2": "Two labels were used for a single array. The node 'arraySampleLabels' specifying which samples were labelled by which compounds will be expected.",
                  "3": "Three labels were used for a single array. The node 'arraySampleLabels' specifying which samples were labelled by which compounds will be expected.",
                  "4": "Four labels were used for a single array. The node 'arraySampleLabels' specifying which samples were labelled by which compounds will be expected."
                }
              },
              "arraySampleLabels": {
                "type": "array",
                "title": "Array of sampleLabel pairs of the array assay",
                "description": "Sample-Label pairs (e.g. sample 'EGAN00000000001' and label 'Cy3') to know which samples used in this assay are labelled by which chemicals. Can be omitted if the array is of one single label/colour.",
                "minItems": 1,
                "additionalProperties": false,
                "uniqueItems": true,
                "items": { 
                  "$ref": "./EGA.common-definitions.json#/$defs/sampleLabelAssociation"
                }
              }
            },
            "anyOf": [
              {
                "title": "2 labels per array check",
                "description": "If 2 labels were used per array, the sampleLabel specifications will be expected and at least 2 items (one for each label)",
                "required": [ "nLabelsPerArray", "arraySampleLabels" ],
                "properties": {
                  "nLabelsPerArray": { 
                    "const": 2 
                  },
                  "arraySampleLabels": {
                    "minItems": 2
                  }
                }
              },
              {
                "title": "3 labels per array check",
                "description": "If 3 labels were used per array, the sampleLabel specifications will be expected and at least 3 items (one for each label)",
                "required": [ "nLabelsPerArray", "arraySampleLabels" ],
                "properties": {
                  "nLabelsPerArray": { 
                    "const": 3 
                  },
                  "arraySampleLabels": {
                    "minItems": 3
                  }
                }
              },
              {
                "title": "4 labels per array check",
                "description": "If 4 labels were used per array, the sampleLabel specifications will be expected and at least 4 items (one for each label)",
                "required": [ "nLabelsPerArray", "arraySampleLabels" ],
                "properties": {
                  "nLabelsPerArray": { 
                    "const": 4 
                  },
                  "arraySampleLabels": {
                    "minItems": 4
                  }
                }
              }           
            ]
          },
          "sequencingAssaySpecifications": {
            "type": "object",
            "title": "Specifications of a sequencing assay",
            "description": "Node containing the set of fields specific to an assay of type 'sequencer' (i.e. a sequencer was used to obtain the raw data).",
            "additionalProperties": false,
            "properties": {
              "referenceAlignmentDetails": {
                "title": "Reference assembly and sequence details",
                "description": "Node containing details of the reference sequence used in the alignment.",
                "$ref": "./EGA.common-definitions.json#/$defs/referenceAlignmentDetails"
              }
            }
          }
        },
        "allOf": [
          {
            "title": "If the assay is of type array its specifications will be expected",
            "if": {
              "required": ["assayInstrument"],
              "properties": {
                "assayInstrument": {
                      "enum": ["array"]
                }
              }
            },
            "then": {
              "required": ["arrayAssaySpecifications"]
            }
          }
        ]
      },

      "assayRelationships": {
        "type": "array",
        "title": "Assay relationships",
        "description": "Comprises metadata (e.g. Source or Target) of a directional association between two entities, one of which shall be the current assay.",
        "minItems": 1,
        "additionalProperties": false,
        "uniqueItems": true,
        "items": { 
          "allOf": [
            {
              "title": "Inherited relationship node",
              "$ref": "./EGA.common-definitions.json#/$defs/relationshipObject"
            },
            {
              "title": "Relationship constraints for an assay",
              "description": "Not all possible relationships between objects are allowed (e.g. an individual should not be linked to a policy). This node contains the restricted relationships that can be given for a XXXXX.",
              "anyOf": [
                {
                  "title": "Allowed relationships of type referencedBy (main ones)",
                  "allOf": [
                    {
                      "$ref": "./EGA.common-definitions.json#/$defs/rTypeReferencedBy"
                    },
                    {
                      "anyOf": [
                        {
                          "$ref": "./EGA.common-definitions.json#/$defs/rTargetDataset"
                        },
                        {
                          "$ref": "./EGA.common-definitions.json#/$defs/rTargetAnalysis"
                        },
                        {
                          "$ref": "./EGA.common-definitions.json#/$defs/rSourceSample"
                        },
                        {
                          "$ref": "./EGA.common-definitions.json#/$defs/rSourceExperiment"
                        },
                        {
                          "$ref": "./EGA.common-definitions.json#/$defs/rSourceSubmission"
                        }
                      ]
                    }
                  ]                  
                },
                {
                  "title": "Allowed relationships of type groupedWith, isAfter, sameAs (optional ones)",
                  "allOf": [
                    {
                      "anyOf": [
                        {
                          "$ref": "./EGA.common-definitions.json#/$defs/rTypeGroupedWith"
                        },
                        {
                          "$ref": "./EGA.common-definitions.json#/$defs/rTypeIsAfter"
                        },
                        {
                          "$ref": "./EGA.common-definitions.json#/$defs/rTypeSameAs"
                        }
                      ]
                    },
                    {
                      "anyOf": [
                        {
                          "$ref": "./EGA.common-definitions.json#/$defs/rSourceAssay"
                        },
                        {
                          "$ref": "./EGA.common-definitions.json#/$defs/rTargetAssay"
                        }
                      ]
                    }
                  ]
                },
                {
                  "title": "Relationships of external accessions and URLs (optional ones)",
                  "description": "Almost any relationship is imaginable with external accessions and URLs.",
                  "allOf": [
                    {
                      "anyOf": [
                        {
                          "$ref": "./EGA.common-definitions.json#/$defs/rTypeChildOf"
                        },
                        {
                          "$ref": "./EGA.common-definitions.json#/$defs/rTypeFamilyRelationshipWith"
                        },
                        {
                          "$ref": "./EGA.common-definitions.json#/$defs/rTypeGroupedWith"
                        },
                        {
                          "$ref": "./EGA.common-definitions.json#/$defs/rTypeSameAs"
                        },
                        {
                          "$ref": "./EGA.common-definitions.json#/$defs/rTypeReferencedBy"
                        },
                        {
                          "$ref": "./EGA.common-definitions.json#/$defs/rTypeDevelopsFrom"
                        },
                        {
                          "$ref": "./EGA.common-definitions.json#/$defs/rTypeMemberOf"
                        },
                        {
                          "$ref": "./EGA.common-definitions.json#/$defs/rTypeIsAfter"
                        }
                      ]
                    },
                    {
                      "anyOf": [
                        {
                          "$ref": "./EGA.common-definitions.json#/$defs/rSourceExternalAccession"
                        },
                        {
                          "$ref": "./EGA.common-definitions.json#/$defs/rSourceExternalURL"
                        },
                        {
                          "$ref": "./EGA.common-definitions.json#/$defs/rTargetExternalAccession"
                        },
                        {
                          "$ref": "./EGA.common-definitions.json#/$defs/rTargetExternalURL"
                        }
                      ]
                    }
                  ]
                }
              ]
            }
          ] 
        },
        "contains": {
          "title": "Constraint to have at least one 'submission' relationship",
          "$ref": "./EGA.common-definitions.json#/$defs/rConstraintOneSourcedSubmission"
        }
      },

      "assayFiles": {
        "type": "array",
        "title": "Data files produced from an assay",
        "description": "This property contains the specific files (e.g. raw CRAM files) derived from performing the sequencing or hybridization and scanning with the sampled material.",
        "minItems": 1,
        "additionalProperties": false,
        "uniqueItems": true,
        "items": {
          "allOf": [
            {
              "title": "Basic file object",
              "$ref": "./EGA.common-definitions.json#/$defs/fileObject"
            },
            {
              "title": "Constraint of filetypes that are allowed for an assay",
              "$ref": "./EGA.common-definitions.json#/$defs/assayFiletypes"
            }
          ]              
        }
      },

      "assayAttributes": {
        "type": "array",
        "title": "Assay custom attributes",
        "description": "Custom attributes of an assay: reusable attributes to encode tag-value pairs (e.g. Tag being 'additional context' and its Value 'this specific assay was stored mistakenly for longer periods of time, so its data could be misleading...') with optional units. Its properties are inherited from the common-definitions.json schema.",
        "minItems": 1,
        "additionalProperties": false,
        "uniqueItems": true,
        "items": { 
          "$ref": "./EGA.common-definitions.json#/$defs/customAttribute" 
        }
      }

    },
    "allOf": [
      {
        "title": "If the files are aligned reads, the reference alignment details are expected",
        "if": {
          "properties": {
            "assayFiles": {
              "items": {
                "properties": {
                  "filetype": {
                    "enum": [ "BAM", "CRAM" ]
                  }
                } 
              }
            }
          }
        },
        "then": {
          "properties": {
            "assayTypeSpecifications": {
              "required": ["sequencingAssaySpecifications"],
              "properties": {
                "sequencingAssaySpecifications": {
                  "required": ["referenceAlignmentDetails"]
                }
              }
            }
          }
        }
      },
      {
        "title": "Allowed filetypes for a sequencing assay",
        "if": {
          "properties": {
            "assayTypeSpecifications": {
              "properties": {
                "assayInstrument": {
                  "const": "sequencer"
                }
              }
            }
          }
        },
        "then": {
          "properties": {
            "assayFiles": {
              "items": {
                "properties": {
                  "filetype": {
                    "enum": [ "FASTQ", "FASTA", "SRA", "SRF", "SFF", "BAM", "CRAM" ]
                  }
                } 
              }
            }
          }
        }
      },
      {
        "title": "Allowed filetypes for an array assay",
        "if": {
          "properties": {
            "assayTypeSpecifications": {
              "properties": {
                "assayInstrument": {
                  "const": "array"
                }
              }
            }
          }
        },
        "then": {
          "properties": {
            "assayFiles": {
              "items": {
                "properties": {
                  "filetype": {
                    "enum": ["CEL", "TSV", "XLSX", "CSV", "IDAT", "TXT", "EXP", "GPR"]
                  }
                } 
              }
            }
          }
        }
      }
    ]
  }