update of inline descriptions in the analysis schema document

* clarifications, rewording, example
* no schema changes

framework/json/responses/sections/beaconFilteringTermsResults.json

@@ -21,24 +21,32 @@
                     ],
                     "type": "string"
                 },
+                "scopes": {
+                    "description": "Entry types affected by this filter.",
+                    "examples": [
+                        [
+                            "individual",
+                            "biosample",
+                            "analysis",
+                            "run",
+                            "genomicVariation"
+                        ],
+                        [
+                            "biosample"
+                        ]
+                    ],
+                    "items": {
+                        "type": "string"
+                    },
+                    "type": "array"
+                },
                 "type": {
                     "description": "Either \"custom\", \"alphanumeric\" or ontology/terminology full name. TODO: An ontology ... with a registered prefix does not need a full name so one may better use CURIE to indicate that the resource can be retrieved from the id. This also will allow to provide an enum here.",
                     "examples": [
                         "Human Phenotype Ontology",
                         "alphanumeric"
                     ],
                     "type": "string"
-                },
-                "scopes": {
-                    "description": "Entry types affected by this filter.",
-                    "examples": [
-                        ["individual", "biosample", "analysis", "run", "genomicVariation"], 
-                        ["biosample"]
-                    ],
-                    "type": "array",
-                    "items": {
-                        "type": "string"
-                    }
                 }
             },
             "required": [
@@ -115,4 +123,4 @@
         }
     },
     "type": "object"
-}
+}

models/json/beacon-v2-default-model/analyses/defaultSchema.json

@@ -2,69 +2,73 @@
     "$comment": "version: ga4gh-beacon-analysis-v2.0.0",
     "$schema": "https://json-schema.org/draft/2020-12/schema",
     "additionalProperties": true,
-    "description": "Schema for a sequencing bioinformatics analysis.",
+    "description": "The `analysis` schema represents a information about the data analysis steps leading to (a set of) genomic variation call(s).",
     "properties": {
         "aligner": {
-            "description": "Reference to mapping/alignment software",
+            "description": "Name or identifier of the mapping/alignment software/pipeline",
             "examples": [
                 "bwa-0.7.8"
             ],
             "type": "string"
         },
         "analysisDate": {
-            "description": "Date at which analysis was performed.",
+            "description": "Date at which analysis was performed.\n",
             "examples": [
                 "2021-10-17"
             ],
             "format": "date",
             "type": "string"
         },
         "biosampleId": {
-            "description": "Reference to the `id` of the biosample this analysis is reporting on.",
+            "description": "Local reference to the `id` of the biosample this analysis is reporting on.",
             "examples": [
-                "S0001"
+                "S0001",
+                "onekgbs-NA07346"
             ],
             "type": "string"
         },
         "id": {
-            "description": "Analysis reference ID (external accession or internal ID)",
+            "description": "Analysis id for internal referencing; unique in the dataset.",
             "type": "string"
         },
         "individualId": {
-            "description": "Reference to the `id` of the individual this analysis is reporting on.",
+            "description": "Local reference to the `id` of the individual this analysis is reporting on.",
             "examples": [
-                "P0001"
+                "P0001",
+                "onekgind-NA07346"
             ],
             "type": "string"
         },
         "info": {
             "$ref": "https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/framework/json/common/beaconCommonComponents.json#/definitions/Info"
         },
         "pipelineName": {
-            "description": "Analysis pipeline and version if a standardized pipeline was used",
+            "description": "Analysis pipeline and version.",
             "examples": [
                 "Pipeline-panel-0001-v1"
             ],
             "type": "string"
         },
         "pipelineRef": {
-            "description": "Link to Analysis pipeline resource",
+            "description": "Link to information about or repository of the analysis pipeline.",
             "examples": [
-                "https://doi.org/10.48511/workflowhub.workflow.111.1"
+                "https://doi.org/10.48511/workflowhub.workflow.111.1",
+                "https://doi.org/10.1093/bib/bbad541"
             ],
             "type": "string"
         },
         "runId": {
-            "description": "Run identifier (external accession or internal ID).",
+            "description": "Local reference to the associated experimental run.",
             "examples": [
                 "SRR10903401"
             ],
             "type": "string"
         },
         "variantCaller": {
-            "description": "Reference to variant calling software / pipeline",
+            "description": "Name or identifier of the variant calling software/pipeline",
             "examples": [
-                "GATK4.0"
+                "GATK4.0",
+                "labelSeg"
             ],
             "type": "string"
         }
@@ -74,6 +78,6 @@
         "analysisDate",
         "pipelineName"
     ],
-    "title": "Sequencing bioinformatics analysis",
+    "title": "Bioinformatics analysis",
     "type": "object"
 }

models/json/beacon-v2-default-model/common/age.json

@@ -3,7 +3,7 @@
     "description": "Age value definition. Provenance: GA4GH Phenopackets v2 `Age`",
     "properties": {
         "iso8601duration": {
-            "description": "Represents age as a ISO8601 duration (e.g., 'P40Y10M05D').",
+            "description": "Represents age as a ISO8601 duration (e.g., P40Y10M05D).",
             "example": "P32Y6M1D",
             "type": "string"
         }
@@ -13,4 +13,4 @@
     ],
     "title": "Age",
     "type": "object"
-}
+}

models/json/beacon-v2-default-model/common/ageRange.json

@@ -12,8 +12,8 @@
         }
     },
     "required": [
-        "end",
-        "start"
+        "start",
+        "end"
     ],
     "title": "AgeRange",
     "type": "object"

models/json/beacon-v2-default-model/common/complexValue.json

@@ -40,7 +40,9 @@
             "type": "array"
         }
     },
-    "required": [ "typedQuantities" ],
+    "required": [
+        "typedQuantities"
+    ],
     "title": "Complex Value",
     "type": "object"
 }

models/json/beacon-v2-default-model/genomicVariations/requestParameters.json

@@ -17,7 +17,7 @@
                 "$ref": "./requestParametersComponents.json#/definitions/Assembly"
             },
             "end": {
-                "description": "Precise or bracketing the end of the variants of interest: * (0-based, exclusive) - see `start` * for bracket queries, provide 2 values (e.g. [111,222]).",
+                "description": "Precise or bracketing the end of the variants of interest: * (0-based, exclusive) - see `start` * for bracket queries, provide 2 values (e.g. [111,222]).\"",
                 "items": {
                     "format": "int64",
                     "minimum": 1,
@@ -52,7 +52,7 @@
                 "$ref": "./requestParametersComponents.json#/definitions/RefSeqId"
             },
             "start": {
-                "description": "Precise or fuzzy start coordinate position(s), allele locus (0-based, inclusive). * `start` only:\n  - for single positions, e.g. the start of a specified sequence\nalteration where the size is given through the specified `alternateBases`\n  - typical use are queries for SNV and small InDels\n  - the use of `start` without an `end` parameter requires the use of\n`alternateBases`\n* 1 value each in both `start` and `end`:\n  - for searching any variant falling fully or partially within the range\n    between `start` and `end` (a.k.a. \"range query\")\n  - additional use of `variantType` OR `alternateBases` can limit the\n    scope of the query\n  - by convention, partial overlaps of variants with the indicated genomic\n    range are accepted; for specific overlap requirements the 4-parameter\n    \"Bracket Queries\" should be employed\n* 2 values in both `start` and `end` for constructing a \"Bracket Query\":\n  - can be used to match any contiguous genomic interval, e.g. for querying\n    imprecise positions\n  - identifies all structural variants starting between `start[0]` and `start[1]`,\n    and ending between `end[0]` <-> `end[1]`\n  - single or double sided precise matches can be achieved by setting\n    `start[1]=start[0]+1` and `end[1]=end[0]+1`",
+                "description": "Precise or fuzzy start coordinate position(s), allele locus (0-based, inclusive). * `start` only:\n  - for single positions, e.g. the start of a specified sequence\n    alteration where the size is given through the specified `alternateBases`\n  - typical use are queries for SNV and small InDels\n  - the use of `start` without an `end` parameter requires the use of\n    `alternateBases`\n* 1 value in both `start` and `end`:\n  - for searching any variant falling fully or partially within the range\n    between `start` and `end` (a.k.a. \"range query\")\n  - additional use of `variantType` OR `alternateBases` can limit the\n    scope of the query\n  - by convention, partial overlaps of variants with the indicated genomic\n    range are accepted; for specific overlap requirements the 4-parameter\n    \"Bracket Queries\" should be employed\n* 2 values in both `start` and `end` for constructing a \"Bracket Query\":\n  - can be used to match any contiguous genomic interval, e.g. for querying\n    imprecise positions\n  - identifies all structural variants starting between `start[0]` and `start[1]`,\n    and ending between `end[0]` <-> `end[1]`\n  - single or double sided precise matches can be achieved by setting\n    `start[1]=start[0]+1` and `end[1]=end[0]+1`",
                 "items": {
                     "format": "int64",
                     "minimum": 0,
@@ -87,4 +87,4 @@
         },
         "type": "object"
     }
-}
+}

models/src/beacon-v2-default-model/analyses/defaultSchema.yaml

@@ -1,55 +1,68 @@
 $schema: https://json-schema.org/draft/2020-12/schema
-title: Sequencing bioinformatics analysis
+title:  Bioinformatics analysis
 $comment: 'version: ga4gh-beacon-analysis-v2.0.0'
-description: Schema for a sequencing bioinformatics analysis.
+description: >-
+  The `analysis` schema represents a information about the data analysis steps
+  leading to (a set of) genomic variation call(s).
 type: object
 properties:
   id:
-    description: Analysis reference ID (external accession or internal ID)
+    description: >-
+      Analysis id for internal referencing; unique in the dataset.
     type: string
   runId:
-    description: Run identifier (external accession or internal ID).
+    description: >-
+      Local reference to the associated experimental run.
     type: string
     examples:
       - SRR10903401
   biosampleId:
-    description: Reference to the `id` of the biosample this analysis is reporting
-      on.
+    description: >-
+      Local reference to the `id` of the biosample this analysis is reporting on.
     type: string
     examples:
       - S0001
+      - onekgbs-NA07346
   individualId:
-    description: Reference to the `id` of the individual this analysis is reporting
-      on.
+    description: >-
+      Local reference to the `id` of the individual this analysis is reporting on.
     type: string
     examples:
       - P0001
+      - onekgind-NA07346
   analysisDate:
-    description: Date at which analysis was performed.
+    description: >
+      Date at which analysis was performed.
     type: string
     format: date
     examples:
       - '2021-10-17'
   pipelineName:
-    description: Analysis pipeline and version if a standardized pipeline was used
+    description: >-
+      Analysis pipeline and version.
     type: string
     examples:
       - Pipeline-panel-0001-v1
   pipelineRef:
-    description: Link to Analysis pipeline resource
+    description: >-
+      Link to information about or repository of the analysis pipeline.
     type: string
     examples:
       - https://doi.org/10.48511/workflowhub.workflow.111.1
+      - https://doi.org/10.1093/bib/bbad541
   aligner:
-    description: Reference to mapping/alignment software
+    description: >-
+      Name or identifier of the mapping/alignment software/pipeline
     type: string
     examples:
       - bwa-0.7.8
   variantCaller:
-    description: Reference to variant calling software / pipeline
+    description:  >-
+      Name or identifier of the variant calling software/pipeline
     type: string
     examples:
       - GATK4.0
+      - labelSeg
   info:
     $ref: https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/framework/json/common/beaconCommonComponents.json#/definitions/Info
 required: