CAP_schema.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "General Cell Annotation Open Standard",
  "description": "A general, open-standard schema for cell annotations which records connections, types, provenance and evidence.\nThis is designed not to tie-in to a single project (i.e. no tool-specific fields in core schema),and allows for extensions to support ad hoc user fields, new formal schema extensions, and project/tool specific metadata.",
  "type": "object",
  "definitions": {
    "Review": {
      "required": [
        "datestamp",
        "verdict"
      ],
      "additionalProperties": false,
      "properties": {
        "datestamp": {
          "description": "Time and date review was last edited.",
          "type": "string",
          "format": "date-time"
        },
        "reviewer": {
          "description": "Review Author",
          "type": "string"
        },
        "review": {
          "description": "Reviewer's verdict on the annotation.  Must be 'Agree' or 'Disagree'",
          "enum": [
            "Agree",
            "Disagree"
          ]
        },
        "explanation": {
          "description": "Free-text review of annotation. This is required if the verdict is disagree and should include reasons for disagreement."
        }
      }
    },
    "Labelset": {
      "properties": {
        "name": {
          "type": "string",
          "description": "name of annotation key"
        },
        "description": {
          "type": "string",
          "description": "Some text describing what types of cell annotation this annotation key is used to record"
        },
        "annotation_method": {
          "description": "The method used for creating the cell annotations. This MUST be one of the following strings: `'algorithmic'`, `'manual'`, or `'both'` ",
          "type": "string",
          "enum": [
            "algorithmic",
            "manual",
            "both"
          ]
        },
        "automated_annotation": {
          "type": "object",
          "$ref": "#/definitions/automated_annotation"
        }
      },
      "required": [
        "name"
      ]
    },
    "automated_annotation": {
      "type": "object",
      "description": "A set of fields for recording the details of the automated annotation algorithm used.\n(Common 'automated annotation methods' would include PopV, Azimuth, CellTypist, scArches, etc.)",
      "properties": {
        "algorithm_name": {
          "type": "string",
          "description": "The name of the algorithm used. It MUST be a string of the algorithm's name."
        },
        "algorithm_version": {
          "type": "string",
          "description": "The version of the algorithm used (if applicable). It MUST be a string of the algorithm's version, which is typically in the format '[MAJOR].[MINOR]', but other versioning systems are permitted (based on the algorithm's versioning)."
        },
        "algorithm_repo_url": {
          "type": "string",
          "description": "This field denotes the URL of the version control repository associated with the algorithm used (if applicable). It MUST be a string of a valid URL."
        },
        "reference_location": {
          "type": "string",
          "description": "This field denotes a valid URL of the annotated dataset that was the source of annotated reference data. \nThis MUST be a string of a valid URL. The concept of a 'reference' specifically refers to 'annotation transfer' algorithms, whereby a 'reference' dataset is used to transfer cell annotations to the 'query' dataset.",
          "$comment": "This must be optional as it does not apply in all cases - e.g. in the case ML based annotation with no single reference dataset."
        }
      },
      "required": [
        "algorithm_name",
        "algorithm_version",
        "algorithm_repo_url"
      ]
    },
    "Annotation": {
      "type": "object",
      "description": "A collection of fields recording a cell type/class/state annotation on some set of cells, supporting evidence and provenance. As this is intended as a general schema, compulsory fields are kept to a minimum. However, tools using this schema are encouarged to specify a larger set of compulsory fields for publication. \n\nNote: This schema deliberately allows for additional fields in order to support ad hoc user fields, new formal schema extensions and project/tool specific metadata.",
      "required": [
        "labelset",
        "cell_label"
      ],
      "properties": {
        "labelset": {
          "description": "The unique name of the set of cell annotations. \nEach cell within the AnnData/Seurat file MUST be associated with a 'cell_label' value in order for this to be a valid 'cellannotation_setname'.",
          "type": "string"
        },
        "cell_label": {
          "description": "This denotes any free-text term which the author uses to annotate cells, i.e. the preferred cell label name used by the author. Abbreviations are exceptable in this field; refer to 'cell_fullname' for related details. \nCertain key words have been reserved:\n- `'doublets'` is reserved for encoding cells defined as doublets based on some computational analysis\n- `'junk'` is reserved for encoding cells that failed sequencing for some reason, e.g. few genes detected, high fraction of mitochondrial reads\n- `'unknown'` is explicitly reserved for unknown or 'author does not know'\n- `'NA'` is incomplete, i.e. no cell annotation was provided",
          "type": "string"
        },
        "cell_fullname": {
          "description": "This MUST be the full-length name for the biological entity listed in `cell_label` by the author. (If the value in `cell_label` is the full-length term, this field will contain the same value.) \nNOTE: any reserved word used in the field 'cell_label' MUST match the value of this field. \n\nEXAMPLE 1: Given the matching terms 'LC' and 'luminal cell' used to annotate the same cell(s), then users could use either terms as values in the field 'cell_label'. However, the abbreviation 'LC' CANNOT be provided in the field 'cell_fullname'. \n\nEXAMPLE 2: Either the abbreviation 'AC' or the full-length term intended by the author 'GABAergic amacrine cell' MAY be placed in the field 'cell_label', but as full-length term naming this biological entity, 'GABAergic amacrine cell' MUST be placed in the field 'cell_fullname'.",
          "type": "string"
        },
        "cell_ontology_term_id": {
          "description": "This MUST be a term from either the Cell Ontology (https://www.ebi.ac.uk/ols/ontologies/cl) or from some ontology that extends it by classifying cell types under terms from the Cell Ontology\ne.g. the Provisional Cell Ontology (https://www.ebi.ac.uk/ols/ontologies/pcl) or the Drosophila Anatomy Ontology (DAO) (https://www.ebi.ac.uk/ols4/ontologies/fbbt).\n\nNOTE: The closest available ontology term matching the value within the field 'cell_label' (at the time of publication) MUST be used.\nFor example, if the value of 'cell_label' is 'relay interneuron', but this entity does not yet exist in the ontology, users must choose the closest available term in the CL ontology. In this case, it's the broader term 'interneuron' i.e.  https://www.ebi.ac.uk/ols/ontologies/cl/terms?obo_id=CL:0000099.",
          "type": "string"
        },
        "cell_ontology_term": {
          "description": "This MUST be the human-readable name assigned to the value of 'cell_ontology_term_id'",
          "type": "string"
        },
        "cell_ids": {
          "type": "array",
          "description": "List of cell barcode sequences/UUIDs used to uniquely identify the cells within the AnnData/Seurat matrix. Any and all cell barcode sequences/UUIDs MUST be included in the AnnData/Seurat matrix.",
          "items": {
            "type": "string",
            "description": "Cell barcode sequences/UUIDs used to uniquely identify the cells within the AnnData/Seurat matrix. Any and all cell barcode sequences/UUIDs MUST be included in the AnnData/Seurat matrix."
          }
        },
        "rationale": {
          "description": "The free-text rationale which users provide as justification/evidence for their cell annotations. \nResearchers are encouraged to use this field to cite relevant publications in-line using standard academic citations of the form `(Zheng et al., 2020)` This human-readable free-text MUST be encoded as a single string.\nAll references cited SHOULD be listed using DOIs under rationale_dois. There MUST be a 2000-character limit.",
          "type": "string",
          "maxLength": 2000
        },
        "rationale_dois": {
          "description": "A list of valid publication DOIs cited by the author to support or provide justification/evidence/context for 'cell_label'.",
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "marker_gene_evidence": {
          "description": "List of names of genes whose expression in the cells being annotated is explicitly used as evidence for this cell annotation. Each gene MUST be included in the matrix of the AnnData/Seurat file.",
          "type": "array",
          "items": {
            "type": "string",
            "description": "Gene names explicitly used as evidence, which MUST be in the matrix of the AnnData/Seurat file"
          }
        },
        "negative_marker_gene_evidence": {
          "description": "List of names of genes, the absence of expression of which is explicitly used as evidence for this cell annotation. Each gene MUST be included in the matrix of the AnnData/Seurat file.",
          "type": "array",
          "items": {
            "type": "string",
            "description": "Gene names explicitly used as evidence, which MUST be in the matrix of the AnnData/Seurat file"
          }
        },
        "synonyms": {
          "description": "This field denotes any free-text term of a biological entity which the author associates as synonymous with the biological entity listed in the field 'cell_label'.\nIn the case whereby no synonyms exist, the authors MAY leave this as blank, which is encoded as 'NA'. However, this field is NOT OPTIONAL.",
          "type": "array",
          "items": {
            "type": "string",
            "description": "List of synonyms"
          }
        },
        "reviews": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/Review"
          }
        },
        "author_annotation_fields": {
          "type": "object",
          "description": "A dictionary of author defined key value pairs annotating the cell set. The names and aims of these fields MUST not clash with official annotation fields."
        },
        "canonical_marker_genes": {
          "description": "A list of gene names considered to be canonical markers for the biological entity used in the cell annotation.",
          "type": "array",
          "items": {
            "type": "string",
            "description": "A gene name recognized as a key marker for the entity's classification."
          }
        },
        "cell_ontology_exists": {
          "description": "Decision by user whether this biological entity exists in the current Cell Ontology or not (at the given time of publication).",
          "type": "boolean"
        },
        "category_fullname": {
          "description": "Any term denoting a biological entity which the author associates as the nearest \"class\" or \"broader term\" (or \"parent term\") for the value/term in the field.",
          "type": "string"
        },
        "category_cell_ontology_exists": {
          "description": "Decision by user whether this biological entity exists in the current Cell Ontology or not (at the given time of publication).",
          "type": "boolean"
        },
        "category_cell_ontology_term_id": {
          "description": "The ID from either the Cell Ontology or from some ontology that extends it by classifying cell types under terms from the Cell Ontology.",
          "type": "string"
        },
        "category_cell_ontology_term": {
          "description": "The human-readable name assigned to the value of 'category_cell_ontology_term_id'",
          "type": "string"
        },
        "cell_ontology_assessment": {
          "description": "Free-text field for researchers to express disagreements with any aspect of the Cell Ontology for this cell annotation.",
          "type": "string"
        }
      }
    }
  },
  "required": [
    "author_name",
    "title",
    "annotations",
    "labelsets",
    "cellannotation_schema_version",
    "cellannotation_timestamp",
    "cellannotation_version",
    "cellannotation_url"
  ],
  "properties": {
    "matrix_file_id": {
      "description": "A resolvable ID for a cell by gene matrix file in the form namespace:accession, e.g. CellXGene_dataset:8e10f1c4-8e98-41e5-b65f-8cd89a887122.  Please see https://github.com/cellannotation/cell-annotation-schema/registry/registry.json for supported namespaces.",
      "type": "string"
    },
    "title": {
      "description": "The title of the dataset. This MUST be less than or equal to 200 characters. e.g. 'Human retina cell atlas - retinal ganglion cells'.",
      "type": "string"
    },
    "description": {
      "description": "The description of the dataset. e.g. 'A total of 15 retinal ganglion cell clusters were identified from over 99K retinal ganglion cell nuclei in the current atlas. Utilizing previous characterized markers from macaque, 5 clusters can be annotated.'",
      "type": "string"
    },
    "cellannotation_schema_version": {
      "description": "The schema version, the cell annotation open standard. Current version MUST follow 0.1.0\nThis versioning MUST follow the format `'[MAJOR].[MINOR].[PATCH]'` as defined by Semantic Versioning 2.0.0, https://semver.org/",
      "type": "string"
    },
    "cellannotation_timestamp": {
      "description": "The timestamp of all cell annotations published (per dataset). This MUST be a string in the format `'%yyyy-%mm-%dd %hh:%mm:%ss'`",
      "type": "string",
      "format": "date-time"
    },
    "cellannotation_version": {
      "description": "The version for all cell annotations published (per dataset). This MUST be a string. The recommended versioning format is `'[MAJOR].[MINOR].[PATCH]'` as defined by Semantic Versioning 2.0.0, https://semver.org/",
      "type": "string"
    },
    "cellannotation_url": {
      "description": "A persistent URL of all cell annotations published (per dataset). ",
      "type": "string"
    },
    "author_list": {
      "description": "This field stores a list of users who are included in the project as collaborators, regardless of their specific role. An example list; '['John Smith', 'Cody Miller', 'Sarah Jones']'",
      "type": "string"
    },
    "author_name": {
      "description": "Primary author's name. This MUST be a string in the format `[FIRST NAME] [LAST NAME]`",
      "type": "string"
    },
    "author_contact": {
      "description": "Primary author's contact. This MUST be a valid email address of the author",
      "type": "string",
      "format": "email"
    },
    "orcid": {
      "description": "Primary author's orcid. This MUST be a valid ORCID for the author",
      "type": "string"
    },
    "labelsets": {
      "type": "array",
      "items": {
        "$ref": "#/definitions/Labelset"
      }
    },
    "annotations": {
      "type": "array",
      "items": {
        "$ref": "#/definitions/Annotation"
      }
    },
    "cap_publication_title": {
      "type": "string",
      "description": "The title of the publication on CAP (i.e. a published collection of datasets, the \"CAP Workspace\".). The title of the publication on CAP. (NOTE: the term \"publication\" refers to the workspace published on CAP with a version and timestamp.) This MUST be less than or equal to N characters, and this MUST be encoded as a single string."
    },
    "cap_publication_description": {
      "type": "string",
      "description": "The description of the publication on CAP. The description of the publication on CAP. (NOTE: the term \"publication\" refers to the workspace published on CAP with a version and timestamp.) This MUST be less than or equal to N characters, and this MUST be encoded as a single string."
    },
    "cap_publication_url": {
      "type": "string",
      "description": "A persistent URL of the publication on CAP. (NOTE: the term \"publication\" refers to the workspace published on CAP with a version and timestamp.)"
    },
    "publication_timestamp": {
      "type": "string",
      "description": "The timestamp of the CAP publication. This MUST be a string in the format %yyyy-%MM-%dd'T'%hh:%mm:%ss. This value will be overwritten by the newest timestamp upon a new publication."
    },
    "publication_version": {
      "type": "string",
      "description": "The (latest) version of the CAP publication. This value will be overwritten by the newest version upon a new publication (and automatically incremented). This versioning MUST follow the format 'v' + '[integer]', whereby newer versions must be naturally incremented."
    }
  }
}