3. ISA-JSON format

Important

As a pre-requisite to reading this specification, please make sure you have read and understood the ISA Abstract Model that the ISA-Json format is based on.

For detail on ISA framework terminology, please read the ISA Abstract Model specification.

This document describes the ISA Abstract Model reference implementation specified in the JSON format [RFC7159]. The JavaScript Object Notation (JSON) [RFC7159] is a text format for serializing structured data. Objects are rendered as an unordered collection of name-value pairs. The JSON Schema (see [JSON Schema], [JSON Schema Core], and [JSON Schema Validation]) defines a JSON format for describing JSON formats.

Below we provide the schemas and the content rules for valid ISA-JSON documents. Full examples of ISA content as ISA-JSON can be found in the ISA datasets repository, here https://git.io/vD1vx.

We recommend that you study these to better understand the structure of ISA-JSON documents.

3.1. Format

Files SHOULD be encoded using UTF-8.

All ISA-JSON content regarding multiple Study and Assay should fall under one Investigation JSON structure, therefore should be recorded in a single JSON file. The JSON file SHOULD have a .json extension.

Dates SHOULD be supplied in the ISO8601 format YYYY-MM-DD.

For maximal portability file names should only contain only ASCII characters not excluded already (that is A-Za-z0-9._!#$%&+,;=@^(){}'[] - we exclude space as many utilities do not accept spaces in file paths): non-English alphabetic characters cannot be guaranteed to be supported in all locales. It would be good practice to avoid the shell metacharacters (){}'[]$.".

3.2. Schemas

The ISA-JSON schemas define the structure of the ISA-JSON objects that implement the ISA Abstract Model. Here we list the JSON schemas with their corresponding model entity, and provide show the schema implemented.

You can also find these schemas in Github at https://git.io/vPZgD

3.2.1. investigation_schema.json

This schema implements Investigation from the ISA Abstract Model.

Schema:

{
    "$schema": "http://json-schema.org/draft-04/schema",
    "title" : "ISA investigation schema",
    "description" : "JSON-schema representing an investigation in the ISA model",
    "type" : "object",
    "properties" : {
         "@id": { "type": "string", "format": "uri" },
        "filename": { "type" : "string"},
        "identifier" : { "type" : "string" },
        "title" : { "type" : "string"},
        "description" : { "type" : "string"},
        "submissionDate" : { "type" : "string", "format" : "date-time"},
        "publicReleaseDate" : { "type" : "string", "format" : "date-time"},
        "ontologySourceReferences" : {
            "type" : "array",
            "items" : {
                "$ref": "ontology_source_reference_schema.json#"
            }
        },
        "publications" : {
            "type" : "array",
            "items" : {
                 "$ref": "publication_schema.json#"

            }
        },
        "people" : {
            "type" : "array",
            "items" : {
                 "$ref": "person_schema.json#"

            }
        },
        "studies" : {
            "type" : "array",
            "items" : {
                 "$ref": "study_schema.json#"

            }
        },
        "comments" : {
            "type": "array",
            "items": {
                 "$ref": "comment_schema.json#"
            }
        }
    },
    "additionalProperties": false
}

3.2.2. study_schema.json

This schema implements Study from the ISA Abstract Model.

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Study JSON Schema",
  "description": "JSON Schema describing an Study",
  "@context": {
    "@base": "http://purl.org/isaterms/",
    "xsd": "http://www.w3.org/2001/XMLSchema#"
  },
  "type": "object",
  "properties": {
    "@id": { "type": "string", "format": "uri" },
    "filename" : { "type" : "string"},
    "identifier" : { "type" : "string" },
    "title" : { "type" : "string"},
    "description" : { "type" : "string"},
    "submissionDate" : { "type" : "string", "format" : "date-time"},
    "publicReleaseDate" : { "type" : "string", "format" : "date-time"},
    "publications" : {
      "type" : "array",
      "items" : {
        "$ref": "publication_schema.json#"
      }
    },
    "people" : {
      "type" : "array",
      "items" : {
        "$ref": "person_schema.json#"

      }
    },
    "studyDesignDescriptors":{
      "type": "array",
      "items" : {
        "$ref": "ontology_annotation_schema.json#"
      }
    },
    "protocols" : {
      "type": "array",
      "items" : {
        "$ref": "protocol_schema.json#"
      }
    },
    "materials": {
      "type": "object",
      "properties": {
        "sources": {
          "type": "array",
          "items": {
            "$ref": "source_schema.json#"
          }
        },
        "samples": {
          "type": "array",
          "items": {
            "$ref": "sample_schema.json#"
          }
        },
        "otherMaterials": {
          "type": "array",
          "items": {
            "$ref": "material_schema.json#"
          }
        }
      }
    },
    "processSequence": {
      "type": "array",
      "items" : {
        "$ref" : "process_schema.json#"
      }
    },
    "assays" : {
      "type": "array",
      "items" : {
        "$ref": "assay_schema.json#"
      }
    },
    "factors": {
      "type": "array",
      "items": {
        "$ref": "factor_schema.json#"
      }
    },
    "characteristicCategories": {
      "description": "List of all the characteristics categories (or material attributes) defined in the study, used to avoid duplication of their declaration when each material_attribute_value is created. ",
      "type": "array",
      "items": {
        "$ref": "material_attribute_schema.json#"
      }
    },
    "unitCategories": {
      "description": "List of all the unitsdefined in the study, used to avoid duplication of their declaration when each value is created. ",
      "type": "array",
      "items": {
        "$ref": "ontology_annotation_schema.json#"
      }
    },
    "comments" : {
      "type": "array",
      "items": {
        "$ref": "comment_schema.json#"
      }
    }
  },
  "additionalProperties": false
}

3.2.3. assay_schema.json

This schema implements Assay from the ISA Abstract Model.

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Assay JSON Schema",
  "name": "Assay JSON Schema",
  "description": "JSON Schema describing an Assay",
  "@context": {
    "@base": "http://purl.org/isaterms/",
    "xsd": "http://www.w3.org/2001/XMLSchema#"
  },
  "type": "object",
  "properties": {
    "@id": { "type": "string", "format": "uri" },
    "comments" : {
      "type": "array",
      "items": {
        "$ref": "comment_schema.json#"
      }
    },
    "filename" : { "type" : "string" },
    "measurementType" : {
      "$ref": "ontology_annotation_schema.json#"
    },
    "technologyType" : {
      "type" : "object",
      "properties": {
        "ontologyAnnotation" : {
          "$ref": "ontology_annotation_schema.json#"
        }
      }
    },
    "technologyPlatform" : { "type" : "string"},
    "dataFiles" : {
      "type": "array",
      "items" : {
        "$ref": "data_schema.json#"
      }
    },
    "materials": {
      "type": "object",
      "properties": {
        "samples": {
          "type": "array",
          "items": {
            "$ref": "sample_schema.json#"
          }
        },
        "otherMaterials": {
          "type": "array",
          "items": {
            "$ref": "material_schema.json#"
          }
        }
      }
    },
    "characteristicCategories": {
      "description": "List of all the characteristics categories (or material attributes) defined in the study, used to avoid duplication of their declaration when each material_attribute_value is created. ",
      "type": "array",
      "items": {
        "$ref": "material_attribute_schema.json#"
      }
    },
    "unitCategories": {
      "description": "List of all the unitsdefined in the study, used to avoid duplication of their declaration when each value is created. ",
      "type": "array",
      "items": {
        "$ref": "ontology_annotation_schema.json#"
      }
    },
    "processSequence": {
      "type": "array",
      "items" : {
        "$ref" : "process_schema.json#"
      }
    }
  },
  "additionalProperties": false
}

3.2.4. comment_schema.json

This schema implements the ability to annotate objects with user-defined comments.

Schema:

{
    "$schema": "http://json-schema.org/draft-04/schema",
    "title": "ISA comment schema - it corresponds to ISA Comment[] construct",
    "description": "JSON-schema representing a comment in the ISA model",
    "type": "object",
    "properties": {
        "@id": { "type": "string", "format": "uri" },
        "name": {
            "type": "string"
        },
        "value": {
            "type": "string"
        }
    },
    "additionalProperties": false
}

3.2.5. data_schema.json

This schema implements Data from the ISA Abstract Model.

Schema:

{
    "$schema": "http://json-schema.org/draft-04/schema",
    "title": "ISA data schema",
    "description": "JSON-schema representing a data file in the ISA model",
    "type": "object",
    "properties": {
        "@id": { "type": "string", "format": "uri" },
        "name": {
            "type": "string"
        },
        "type": {
            "type": "string",
            "enum": [
                "Raw Data File",
                "Derived Data File",
                "Image File"
            ]
        },
        "comments" : {
            "type": "array",
            "items": {
                "$ref": "comment_schema.json#"
            }
        }
    },
    "additionalProperties": false
}

3.2.6. factor_schema.json

This schema implements Study factor from the ISA Abstract Model.

Schema:

{
    "$schema": "http://json-schema.org/draft-04/schema",
    "title": "ISA factor schema",
    "name": "ISA factor schema",
    "description": "JSON-schema representing a factor value in the ISA model",
    "type": "object",
    "properties": {
        "@id": { "type": "string", "format": "uri" },
        "factorName": {
            "type": "string"
        },
        "factorType": {
            "$ref": "ontology_annotation_schema.json#"
        },
        "comments" : {
            "type": "array",
            "items": {
                 "$ref": "comment_schema.json#"
            }
        }
    },
    "additionalProperties": false
}

3.2.7. factor_value_schema.json

This schema implements Factor value given to a node corresponding to a declared Factor.

Schema:

{
    "$schema": "http://json-schema.org/draft-04/schema",
    "title": "ISA factor value schema",
    "description": "JSON-schema representing a factor value in the ISA model",
    "type": "object",
    "properties": {
         "@id": { "type": "string", "format": "uri" },
         "category" : {
             "$ref": "factor_schema.json#"
        },
        "value": {
            "anyOf" : [
                { "$ref": "ontology_annotation_schema.json#"},
                { "type": "string"},
                { "type": "number"}
                ]
        },
        "unit": {
            "$ref": "ontology_annotation_schema.json#"
        }
    },
    "additionalProperties": false
}

3.2.8. material_attribute_schema.json

This schema is used in a Material node to declare an attribute (Characteristic).

Schema:

{
    "$schema": "http://json-schema.org/draft-04/schema",
    "title" : "ISA material attribute schema",
    "description" : "JSON-schema representing a characteristics category (what appears between the brackets in Charactersitics[]) in the ISA model",
    "type" : "object",
    "properties" : {
        "@id": { "type": "string", "format": "uri" },
        "characteristicType": {
            "$ref": "ontology_annotation_schema.json#"
        }
    },
    "additionalProperties": false
}

3.2.9. material_attribute_value_schema.json

This schema is used in a Material node to hold an attribute value (value of a Characteristic).

Schema:

{
    "$schema": "http://json-schema.org/draft-04/schema",
    "title" : "ISA material attribute schema",
    "description" : "JSON-schema representing a material attribute (or characteristic) value in the ISA model",
    "type" : "object",
    "properties" : {
         "@id": { "type": "string", "format": "uri" },
        "category" : {
             "$ref": "material_attribute_schema.json#"
        },
        "value": {
            "anyOf" : [
                { "$ref": "ontology_annotation_schema.json#"},
                { "type": "string"},
                { "type": "number"}
                ]
        },
        "unit": {
            "$ref": "ontology_annotation_schema.json#"
        }
    },
    "additionalProperties": false
}

3.2.10. material_schema.json

This schema implements Material nodes from the ISA Abstract Model.

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "title" : "ISA material node schema",
  "description" : "JSON-schema representing a material node in the ISA model, which is not a source or a sample (as they have specific schemas) - this will correspond to 'Extract Name', 'Labeled Extract Name'",
  "type" : "object",
  "properties" : {
    "@id": { "type": "string", "format": "uri" },
    "name" : { "type" : "string" },
    "type": {
      "type": "string",
      "enum": [
        "Extract Name",
        "Labeled Extract Name"
      ]
    },
    "characteristics" : {
      "type" : "array",
      "items" :  {
        "$ref": "material_attribute_value_schema.json#"
      }
    },
    "derivesFrom": {
      "type" : "array",
      "items" : {
        "$ref": "material_schema.json#"
      }
    }
  },
  "additionalProperties": false
}

3.2.11. ontology_annotation_schema.json

This schema implements Ontology from the ISA Abstract Model.

Schema:

{
    "$schema": "http://json-schema.org/draft-04/schema",
    "title" : "ISA ontology reference schema",
    "name" : "ISA ontology reference schema",
    "description" : "JSON-schema representing an ontology reference or annotation in the ISA model (for fields that are required to be ontology annotations)",
    "type" : "object",
    "properties" : {
        "@id": { "type": "string", "format": "uri" },
        "annotationValue": {
            "anyOf": [
                { "type": "string" },
                { "type": "number"}
            ]
        },
        "termSource" : {
            "type" : "string",
            "description" : "The abbreviated ontology name. It should correspond to one of the sources as specified in the ontologySourceReference section of the Investigation."
        },
        "termAccession" : {
            "type" : "string",
            "format" : "uri"
        },
        "comments" : {
            "type": "array",
            "items": {
                "$ref": "comment_schema.json#"
            }
        }
    },
    "additionalProperties": false
}

3.2.12. ontology_source_reference_schema.json

This schema implements Ontology from the ISA Abstract Model.

Schema:

{
    "$schema": "http://json-schema.org/draft-04/schema",
    "title" : "ISA ontology source reference schema",
    "name" : "ISA ontology source reference schema",
    "description" : "JSON-schema representing an ontology reference in the ISA model",
    "type" : "object",
    "properties" : {
        "comments" : {
            "type": "array",
            "items": {
                 "$ref": "comment_schema.json#"
            }
        },
        "description" : { "type" : "string" },
        "file" : { "type" : "string" },
        "name": {"type": "string"},
        "version": { "type": "string"}
    },
    "additionalProperties": false
}

3.2.13. person_schema.json

This schema implements Contact from the ISA Abstract Model.

Schema:

{
    "$schema": "http://json-schema.org/draft-04/schema",
    "title" : "ISA person schema",
    "description" : "JSON-schema representing a person in the ISA model",
    "type" : "object",
    "properties" : {
        "@id": { "type": "string", "format": "uri" },
        "lastName" : { "type" : "string"},
        "firstName" : { "type" : "string"},
        "midInitials" : { "type" : "string" },
        "email" : { "type" : "string", "format" : "email"},
        "phone" : { "type": "string"},
        "fax" : { "type" : "string" },
        "address" : { "type" : "string" },
        "affiliation" : { "type" : "string" },
        "roles" : {
            "type" : "array",
            "items" : {
                "$ref": "ontology_annotation_schema.json#"
            }
        },
        "comments" : {
            "type": "array",
            "items": {
                 "$ref": "comment_schema.json#"
            }
        }
    },
    "additionalProperties": false
}

3.2.14. process_parameter_value_schema.json

This schema is used in a Process node to hold a parameter value (value of a Protocol parameter).

Schema:

{
    "$schema": "http://json-schema.org/draft-04/schema",
    "title" : "ISA process parameter value schema",
    "description" : "JSON-schema representing a Parameter Value (associated with a Protocol REF) in the ISA model",
    "type" : "object",
    "properties" : {
        "category" : {
             "$ref": "protocol_parameter_schema.json#"
            },
        "value": {
            "anyOf" : [
                { "$ref": "ontology_annotation_schema.json#"},
                { "type": "string"},
                { "type": "number"}
                ]
        },
        "unit": {
            "$ref": "ontology_annotation_schema.json#"
        }
    },
    "additionalProperties": false
}

3.2.15. process_schema.json

This schema implements Process nodes from the ISA Abstract Model.

Schema:

{
    "$schema": "http://json-schema.org/draft-04/schema",
    "title": "ISA process or protocol application schema, corresponds to 'Protocol REF' columns in the study and assay files",
    "description": "JSON-schema representing a protocol application in the ISA model",
    "type": "object",
    "properties": {
        "@id": { "type": "string", "format": "uri" },
        "name": {
            "type": "string"
        },
        "executesProtocol": {
                "$ref": "protocol_schema.json#"
        },
        "parameterValues": {
            "type": "array",
            "items": {
                  "$ref" : "process_parameter_value_schema.json#"
            }
        },
        "performer": {
             "type": "string"
        },
        "date": {
             "type": "string",
              "format": "date-time"
        },
        "previousProcess" : {
             "$ref" : "process_schema.json#"
        },
        "nextProcess": {
             "$ref" : "process_schema.json#"
        },
        "inputs" : {
            "type": "array",
            "items": {
                 "anyOf": [
                   {
                     "$ref": "source_schema.json#"
                   },
                   {
                     "$ref": "sample_schema.json#"
                   },
                   {
                     "$ref": "data_schema.json#"
                   },
                   {
                     "$ref": "material_schema.json#"
                   }
                 ]
            }
        },
        "outputs" : {
            "type": "array",
            "items": {
                 "anyOf": [
                        {
                            "$ref": "sample_schema.json#"
                        },
                        {
                            "$ref": "data_schema.json#"
                        },
                        {
                        "$ref": "material_schema.json#"
                        }
                    ]
            }
        },
        "comments" : {
            "type": "array",
            "items": {
                 "$ref": "comment_schema.json#"
            }
        }
    },
    "additionalProperties": false
}

3.2.16. protocol_parameter_schema.json

This schema is used in a Protocol to describe a protocol parameter.

Schema:

{
    "$schema": "http://json-schema.org/draft-04/schema",
    "title" : "ISA protocol parameter schema",
    "description" : "JSON-schema representing a parameter for a protocol (category declared in the investigation file) in the ISA model",
    "type" : "object",
    "properties" : {
        "@id": { "type": "string", "format": "uri" },
        "parameterName": {
            "$ref": "ontology_annotation_schema.json#"
        }
    },
    "additionalProperties": false
}

3.2.17. protocol_schema.json

This schema implements Protocol from the ISA Abstract Model.

Schema:

{
    "$schema": "http://json-schema.org/draft-04/schema",
    "title": "ISA protocol schema",
    "name": "ISA protocol schema",
    "description": "JSON-schema representing a protocol in the ISA model",
    "type": "object",
    "properties": {
        "@id": { "type": "string", "format": "uri" },
        "comments" : {
            "type": "array",
            "items": {
                 "$ref": "comment_schema.json#"
            }
        },
        "name": {
            "type": "string"
        },
        "protocolType": {
            "$ref": "ontology_annotation_schema.json#"
        },
        "description": {
            "type": "string"
        },
        "uri": {
            "type": "string",
            "format": "uri"
        },
        "version": {
            "type": "string"
        },
        "parameters": {
            "type": "array",
            "items": {
                "$ref": "protocol_parameter_schema.json#"
            }
        },
        "components": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "componentName": {
                        "type": "string"
                    },
                    "componentType": {
                        "$ref": "ontology_annotation_schema.json#"
                    }
                }
            }
        }
    },
    "additionalProperties": false
}

3.2.18. publication_schema.json

This schema implements Publication from the ISA Abstract Model.

Schema:

{
    "$schema": "http://json-schema.org/draft-04/schema",
    "title" : "ISA investigation schema",
    "name" : "ISA investigation schema",
    "description" : "JSON-schema representing an investigation in the ISA model",
    "type" : "object",
    "properties" : {
        "comments" : {
            "type": "array",
            "items": {
                 "$ref": "comment_schema.json#"
            }
        },
        "pubMedID" : { "type" : "string" },
        "doi" : { "type" : "string"},
        "authorList" : { "type" : "string" },
        "title" : { "type" : "string" },
        "status" : {
            "$ref": "ontology_annotation_schema.json#"
        }
    },
    "additionalProperties": false
}

3.2.19. sample_schema.json

This schema implements Sample from the ISA Abstract Model.

Schema:

{
    "$schema": "http://json-schema.org/draft-04/schema",
    "title" : "ISA sample schema",
    "description" : "JSON-schema representing a sample in the ISA model. A sample represents a major output resulting from a protocol application other than the special case outputs of Extract or a Labeled Extract.",
    "type": "object",
    "properties" : {
        "@id": { "type": "string", "format": "uri" },
        "name" : { "type" : "string" },
        "characteristics" : {
            "type" : "array",
            "items" :  {
                "$ref": "material_attribute_value_schema.json#"
            }
        },
        "factorValues" : {
            "type" : "array",
            "items" : {
                "$ref" : "factor_value_schema.json#"
            }
        },
        "derivesFrom": {
            "type" : "array",
            "items" : {
                "$ref": "source_schema.json#"
            }
        }
    },
    "additionalProperties": false
}

3.2.20. source_schema.json

This schema implements Source from the ISA Abstract Model.

Schema:

{
    "$schema": "http://json-schema.org/draft-04/schema",
    "title" : "ISA source schema",
    "description" : "JSON-schema representing a source in the ISA model. Sources are considered as the starting biological material used in a study.",
      "properties" : {
        "@id": { "type": "string", "format": "uri" },
        "name" : { "type" : "string" },
        "characteristics" : {
            "type" : "array",
            "items" :  {
                "$ref": "material_attribute_value_schema.json#"
                }
        }
      },
    "additionalProperties": false
}

3.3. Content rules

The rules described here define the content and relationship rules that the ISA-JSON objects must adhere to to implement ISA Abstract Model.

1. Files SHOULD be encoded using UTF-8.
2. ISA-JSON content MUST be well-formed JSON.
3. ISA-JSON content MUST validate against the ISA-JSON schemas.
4. ISA-JSON files SHOULD be suffixed with a .json extension.
5. Dates SHOULD be supplied in the ISO8601 format “YYYY-MM-DD”.
6. DOIs SHOULD conform to the standard format ISO 26324 DOI format “10.NN/xxxNNNNNN”.
7. PubMed IDs SHOULD be a string of eight numbers (e.g. 12345678), optionally prefixed with PMC (e.g. PMC12345678).
8. Characteristic Categories declared SHOULD be referenced by at least one Characteristic.
9. Characteristics MUST reference a Characteristic Category declaration.
10. Unit Categories declared SHOULD be referenced by at least one Unit.
11. Units MUST reference a Unit Category declaration.
12. All Sources and Samples MUST be declared in the Study-level materials section.
13. All other materials (Extracts etc.) and DataFiles MUST be declared in the Assay-level material and data sections respectively.
14. Each Process in a Process Sequence MUST link with other Processes forwards or backwards, unless it is a starting or terminating Process (i.e. Beginning or end of the experimental graph).
15. Protocols declared SHOULD be referenced by at least one Protocol REF.
16. Protocol REFs MUST reference a Protocol declaration.
17. Study Factors declared SHOULD be referenced by at least one Factor Value.
18. Factor Values MUST reference a Study Factor declared in the Study-level factors section.
19. Protocols SHOULD have a name (in order to be referenced in ISA-Tab).
20. Protocol Parameters SHOULD have a name (in order to be referenced in ISA-Tab).
21. Study Factors SHOULD have a name (in order to be referenced in ISA-Tab).
22. Sources and Samples declared SHOULD be referenced by at least one Process at the Study-level.
23. Samples, other materials, and DataFiles declared SHOULD be used in at least one Process at the Assay-level.
24. Study and Assay filenames SHOULD be present (in order to be referenced in ISA-Tab).
25. Ontology Source References declared SHOULD be referenced by at least one Ontology Annotation.
26. Ontology Annotations MUST reference a Ontology Source Reference declaration.
27. Ontology Source References MUST contain a Term Source Name.
28. Ontology Annotations with a term and/or accession MUST provide a Term Source REF pointing to a declared Ontology Source Reference.
29. Publication metadata SHOULD match that of publication record in PubMed corresponding to the provided PubMed ID.
30. Comments MUST have a name.