feat: add descriptions for output json format

Author: ivan-aksamentov

packages/nextclade-schemas/output-json.schema.json

@@ -1,6 +1,7 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "title": "ResultsJson",
+  "description": "The `nextclade.json` file produced using `nextclade run --output-json`",
   "type": "object",
   "required": [
     "cladeNodeAttrKeys",
@@ -58,6 +59,7 @@
   },
   "definitions": {
     "CladeNodeAttrKeyDesc": {
+      "description": "Description of a clade-like node attribute",
       "type": "object",
       "required": [
         "displayName",
@@ -87,7 +89,7 @@
       }
     },
     "PhenotypeAttrDesc": {
-      "description": "Describes a single attribute of a phenotype",
+      "description": "Description of a phenotype attribute",
       "type": "object",
       "required": [
         "description",
@@ -107,6 +109,7 @@
       }
     },
     "AuspiceRefNodesDesc": {
+      "description": "Describes search criteria in the reference tree nodes. This is used for \"Relative to\" feature where you can switch mutation calling source node between \"reference\", \"parent\", \"clade founder\" and custom nodes described using this format.",
       "type": "object",
       "properties": {
         "default": {
@@ -124,6 +127,7 @@
       }
     },
     "AuspiceRefNodeSearchDesc": {
+      "description": "Describes a criteria for selecting a reference node for \"Relative to\" feature",
       "type": "object",
       "required": [
         "name"
@@ -238,6 +242,8 @@
       ]
     },
     "NextcladeOutputs": {
+      "title": "ResultJson",
+      "description": "Single element in `.results` array in nextclade.json file, produced by `nextclade run --output-json`. This corresponds to a single sequence in the inputs.",
       "type": "object",
       "required": [
         "aaAlignmentRanges",
@@ -634,11 +640,17 @@
           }
         },
         "annotation": {
-          "$ref": "#/definitions/GeneMap"
+          "description": "Genome annotation in query sequence coordinates",
+          "allOf": [
+            {
+              "$ref": "#/definitions/GeneMap"
+            }
+          ]
         }
       }
     },
     "NucSub": {
+      "description": "A nucleotide substitution",
       "type": "object",
       "required": [
         "pos",
@@ -662,6 +674,7 @@
       "format": "int"
     },
     "Nuc": {
+      "description": "A nucleotide",
       "type": "string",
       "enum": [
         "T",
@@ -683,6 +696,7 @@
       ]
     },
     "NucDelRange": {
+      "description": "A nucleotide deletion range",
       "type": "object",
       "required": [
         "range"
@@ -710,6 +724,7 @@
       }
     },
     "Insertion_for_Nuc": {
+      "description": "An insertion",
       "type": "object",
       "required": [
         "ins",
@@ -741,6 +756,7 @@
       }
     },
     "FrameShift": {
+      "description": "A frame shift",
       "type": "object",
       "required": [
         "cdsName",
@@ -832,6 +848,7 @@
       ]
     },
     "AaDel": {
+      "description": "An aminoacid deletion",
       "type": "object",
       "required": [
         "cdsName",
@@ -851,6 +868,7 @@
       }
     },
     "AaIns": {
+      "description": "An amino acid insertion",
       "type": "object",
       "required": [
         "cds",
@@ -871,6 +889,7 @@
       }
     },
     "CdsAaRange": {
+      "description": "A set of ranges of amino acid positions in a translated CDS",
       "type": "object",
       "required": [
         "cdsName",
@@ -914,6 +933,7 @@
       }
     },
     "AaChangesGroup": {
+      "description": "Represents a group of adjacent amino acid changes along with nucleotide changes nearby.",
       "type": "object",
       "required": [
         "changes",
@@ -1014,6 +1034,7 @@
       }
     },
     "PcrPrimerChange": {
+      "description": "A change in a PCR primer due to mutations",
       "type": "object",
       "required": [
         "primer",
@@ -1086,6 +1107,7 @@
       }
     },
     "PrivateNucMutations": {
+      "description": "A collection of private nucleotide mutations",
       "type": "object",
       "required": [
         "labeledSubstitutions",
@@ -1189,6 +1211,7 @@
       }
     },
     "PrivateAaMutations": {
+      "description": "A collection of private amino acid mutations for a CDS",
       "type": "object",
       "required": [
         "aaChangesGroups",
@@ -1264,6 +1287,7 @@
       }
     },
     "CladeNodeAttrFounderInfo": {
+      "description": "Information about a clade-like node attribute founder",
       "type": "object",
       "required": [
         "aaMutations",
@@ -1303,6 +1327,7 @@
       "minimum": 0.0
     },
     "AncestralSearchResult": {
+      "description": "Represents the result of searching for ancestral nodes of interest in the graph",
       "type": "object",
       "required": [
         "search"
@@ -1324,6 +1349,7 @@
       }
     },
     "AncestralSearchResultForCriteria": {
+      "description": "Represents the result of searching for ancestral nodes of interest in the graph",
       "type": "object",
       "required": [
         "criterion"
@@ -1345,6 +1371,7 @@
       }
     },
     "AncestralSearchMatch": {
+      "description": "Represents a match found in the ancestral search",
       "type": "object",
       "required": [
         "nodeKey",
@@ -1396,6 +1423,7 @@
       }
     },
     "RelativeNucMutations": {
+      "description": "Result for a single sequence in the inputs, containing relative nucleotide mutations",
       "type": "object",
       "required": [
         "search"
@@ -1417,6 +1445,7 @@
       }
     },
     "RelativeNucMutationsResult": {
+      "description": "Result for a single criterion in the search, containing relative nucleotide mutations",
       "type": "object",
       "required": [
         "criterion",
@@ -1479,6 +1508,7 @@
       }
     },
     "PeptideWarning": {
+      "description": "A warning about a peptide sequence",
       "type": "object",
       "required": [
         "cdsName",
@@ -1850,6 +1880,7 @@
       }
     },
     "PhenotypeValue": {
+      "description": "Result for a single phenotype value",
       "type": "object",
       "required": [
         "cds",
@@ -1870,6 +1901,7 @@
       }
     },
     "AaMotif": {
+      "description": "Result of amino acid motif search in a translated CDS",
       "type": "object",
       "required": [
         "cds",
@@ -1961,6 +1993,7 @@
       }
     },
     "GeneMap": {
+      "description": "Genome annotation",
       "type": "object",
       "required": [
         "genes"
@@ -2468,6 +2501,7 @@
       }
     },
     "NextcladeErrorOutputs": {
+      "title": "ResultJsonError",
       "type": "object",
       "required": [
         "errors",