diff --git a/framework/json/configuration/beaconConfigurationSchema.json b/framework/json/configuration/beaconConfigurationSchema.json
index 7b3b448e..20c2e055 100644
--- a/framework/json/configuration/beaconConfigurationSchema.json
+++ b/framework/json/configuration/beaconConfigurationSchema.json
@@ -12,7 +12,7 @@
     },
     "$schema": "https://json-schema.org/draft/2020-12/schema",
     "additionalProperties": true,
-    "description": "Files complaint with this schema are the configuration ones. The details returned in `service-info` are mirroring the ones in this configuration file.",
+    "description": "The Beacon configuration reports several attributes of the beacon instance related to security, maturity and available entry types. Where appropriate the details returned in `service-info` should mirror the ones in this configuration.",
     "properties": {
         "$schema": {
             "$ref": "../common/beaconCommonComponents.json#/$defs/$schema"
@@ -24,7 +24,7 @@
             "description": "Declares the level of maturity of the Beacon instance.",
             "properties": {
                 "productionStatus": {
-                    "description": "`DEV`= 'Service potentially unstable, not real data', which availability and data should not be used in production setups. `TEST`= 'Service stable, not real data'. 'PROD'= 'Service stable, actual data'.",
+                    "description": "* `DEV`: Service potentially unstable, _i.e._ potentially not real data,\n  inconsistent availability; data should not be used in production setups   \n* `TEST`: Service is stable but data should be considered synthetic   * `PROD`: Service stable with real world data  ",
                     "enum": [
                         "DEV",
                         "TEST",
diff --git a/framework/json/responses/beaconBooleanResponse.json b/framework/json/responses/beaconBooleanResponse.json
index dc36a6dd..6bc1b912 100644
--- a/framework/json/responses/beaconBooleanResponse.json
+++ b/framework/json/responses/beaconBooleanResponse.json
@@ -1,6 +1,6 @@
 {
     "$schema": "https://json-schema.org/draft/2020-12/schema",
-    "description": "Complete definition for a minimal response that provides *only* a `Boolean` exists true|false answer.",
+    "description": "Complete definition for a minimal response that provides *only* an aggregate Boolean `\"exists\": true` or `\"exists\": false` answer to the query.  \nAdditional information - which should not consist of record-level information - can be provided through `beaconHandovers`.  ",
     "properties": {
         "beaconHandovers": {
             "$ref": "../common/beaconCommonComponents.json#/$defs/ListOfHandovers",
diff --git a/framework/json/responses/beaconCollectionsResponse.json b/framework/json/responses/beaconCollectionsResponse.json
index ca8cdb72..6f819dc0 100644
--- a/framework/json/responses/beaconCollectionsResponse.json
+++ b/framework/json/responses/beaconCollectionsResponse.json
@@ -1,7 +1,7 @@
 {
     "$schema": "https://json-schema.org/draft/2020-12/schema",
     "additionalProperties": true,
-    "description": "Beacon response that includes details about the collections in this Beacon.",
+    "description": "A type of Beacon response that includes details about the **collections** in a beacon. The types of collections are defined in each beacon's configuration; if using the Beacon v2+ default model usually the types `dataset` and `cohort` are supported.",
     "properties": {
         "beaconHandovers": {
             "$ref": "../common/beaconCommonComponents.json#/$defs/ListOfHandovers",
diff --git a/framework/json/responses/beaconConfigurationResponse.json b/framework/json/responses/beaconConfigurationResponse.json
index ccd15687..3551db86 100644
--- a/framework/json/responses/beaconConfigurationResponse.json
+++ b/framework/json/responses/beaconConfigurationResponse.json
@@ -1,7 +1,7 @@
 {
     "$schema": "https://json-schema.org/draft/2020-12/schema",
     "additionalProperties": true,
-    "description": "Information about the Beacon. Aimed to Beacon clients like web pages or Beacon networks.",
+    "description": "The `beaconConfigurationResponse` returns information about configuration parameters of a given beacon instance such as maturity or security attributes or supported entry types. It is directed towards Beacon clients like web pages or network aggregators.",
     "properties": {
         "meta": {
             "$ref": "./sections/beaconInformationalResponseMeta.json",
diff --git a/framework/json/responses/beaconCountResponse.json b/framework/json/responses/beaconCountResponse.json
index acf4ffcc..b3b72f69 100644
--- a/framework/json/responses/beaconCountResponse.json
+++ b/framework/json/responses/beaconCountResponse.json
@@ -1,6 +1,6 @@
 {
     "$schema": "https://json-schema.org/draft/2020-12/schema",
-    "description": "Complete definition for a response that does not include record level details but provides `Boolean` and `count` information.",
+    "description": "Complete definition for a minimal response that provides an aggregate Boolean `\"exists\": true` or `\"exists\": false` answer to the query as well as the count of the matched records.\nAdditional information - which should not consist of record-level information - can be provided through `beaconHandovers`.  ",
     "properties": {
         "beaconHandovers": {
             "$ref": "../common/beaconCommonComponents.json#/$defs/ListOfHandovers",
diff --git a/framework/json/responses/beaconEntryTypesResponse.json b/framework/json/responses/beaconEntryTypesResponse.json
index 2c2cc551..d18fa813 100644
--- a/framework/json/responses/beaconEntryTypesResponse.json
+++ b/framework/json/responses/beaconEntryTypesResponse.json
@@ -1,7 +1,7 @@
 {
     "$schema": "https://json-schema.org/draft/2020-12/schema",
     "additionalProperties": true,
-    "description": "Response including a list of Entry types definitions.",
+    "description": "The `beaconEntryTypesResponse` provides information about the entry types served through a beacon, including their definitions and pointers to their schemas.",
     "properties": {
         "meta": {
             "$ref": "./sections/beaconInformationalResponseMeta.json",
diff --git a/framework/json/responses/beaconErrorResponse.json b/framework/json/responses/beaconErrorResponse.json
index db7b0c0f..3f01c1a1 100644
--- a/framework/json/responses/beaconErrorResponse.json
+++ b/framework/json/responses/beaconErrorResponse.json
@@ -1,7 +1,7 @@
 {
     "$schema": "https://json-schema.org/draft/2020-12/schema",
     "additionalProperties": true,
-    "description": "An unsuccessful operation.",
+    "description": "A `beaconErrorResponse` denotes an unsuccessful operation, e.g. due to a missing parameter or an invalid query. The response contains an error object.",
     "properties": {
         "error": {
             "$ref": "../common/beaconCommonComponents.json#/$defs/BeaconError"
diff --git a/framework/json/responses/beaconInfoResponse.json b/framework/json/responses/beaconInfoResponse.json
index a221e746..5ed2651f 100644
--- a/framework/json/responses/beaconInfoResponse.json
+++ b/framework/json/responses/beaconInfoResponse.json
@@ -1,7 +1,7 @@
 {
     "$schema": "https://json-schema.org/draft/2020-12/schema",
     "additionalProperties": true,
-    "description": "Information about the Beacon. Aimed at Beacon clients like web pages or Beacon networks.",
+    "description": "The `beaconInfoResponse` provides metadata describing a Beacon instance, such as its name, the organization responsible for the Beacon, contact information, site logo and alternative URLs and importantly the beacon's API version. It is based on the GA4GH `service-info` standard.\nThe content of the `beaconInfoResponse` can be used by clients such as web front ends or beacon aggregators to evaluate potential access patterns and to display information about the beacon.",
     "properties": {
         "meta": {
             "$ref": "./sections/beaconInformationalResponseMeta.json",
diff --git a/framework/json/responses/beaconMapResponse.json b/framework/json/responses/beaconMapResponse.json
index d915b4a2..f2c05915 100644
--- a/framework/json/responses/beaconMapResponse.json
+++ b/framework/json/responses/beaconMapResponse.json
@@ -1,7 +1,7 @@
 {
     "$schema": "https://json-schema.org/draft/2020-12/schema",
     "additionalProperties": true,
-    "description": "Information about the Beacon. Aimed to Beacon clients like web pages or Beacon networks.",
+    "description": "A `beaconMapResponse` provides information about the beacon instance such as the different endpoints supported by this implementation of the Beacon API. This response is aimed to allow Beacon clients such as web front ends and Beacon network aggregators to evaluate which access patterns can be implemented against individual beacons.",
     "properties": {
         "meta": {
             "$ref": "./sections/beaconInformationalResponseMeta.json",
diff --git a/framework/json/responses/beaconResultsetsResponse.json b/framework/json/responses/beaconResultsetsResponse.json
index 094ed57a..4a294324 100644
--- a/framework/json/responses/beaconResultsetsResponse.json
+++ b/framework/json/responses/beaconResultsetsResponse.json
@@ -1,7 +1,7 @@
 {
     "$schema": "https://json-schema.org/draft/2020-12/schema",
     "additionalProperties": true,
-    "description": "Beacon response that includes record level details, grouped in Resultsets.",
+    "description": "A `beaconResultsetsResponse` returns the results of a query against a beacon or beacon aggregator. Beyond the `responseSummary` for overall matches the response contains details about the matches in individual **collections** in the beacon or beacon network. This type of response is required when serving a request with a \"record\" level `responseGranularity`, and `beaconResultsets` typically contain a list of records matched by the query.\nThe types of `beaconResultsets` objects are defined in the beacon's configuration; e.g. if using the Beacon v2+ default model the types `dataset` and `cohort` are supported as result sets.    ",
     "properties": {
         "beaconHandovers": {
             "$ref": "../common/beaconCommonComponents.json#/$defs/ListOfHandovers",
diff --git a/framework/src/configuration/beaconConfigurationSchema.yaml b/framework/src/configuration/beaconConfigurationSchema.yaml
index bcd6a64e..6eaef9f2 100644
--- a/framework/src/configuration/beaconConfigurationSchema.yaml
+++ b/framework/src/configuration/beaconConfigurationSchema.yaml
@@ -1,7 +1,9 @@
 $schema: https://json-schema.org/draft/2020-12/schema
 title: Beacon Configuration
-description: Files complaint with this schema are the configuration ones. The details
-  returned in `service-info` are mirroring the ones in this configuration file.
+description: >-
+  The Beacon configuration reports several attributes of the beacon instance related
+  to security, maturity and available entry types.
+  Where appropriate the details returned in `service-info` should mirror the ones in this configuration.
 type: object
 properties:
   $schema:
@@ -11,16 +13,19 @@ properties:
     type: object
     properties:
       productionStatus:
-        description: "`DEV`= 'Service potentially unstable, not real data', which\
-          \ availability and data should not be used in production setups. `TEST`=\
-          \ 'Service stable, not real data'. 'PROD'= 'Service stable, actual data'."
+        description: >-
+          * `DEV`: Service potentially unstable, _i.e._ potentially not real data,
+            inconsistent availability; data should not be used in production setups   
+          * `TEST`: Service is stable but data should be considered synthetic  
+          * `PROD`: Service stable with real world data  
         type: string
         enum:
           - DEV
           - TEST
           - PROD
   securityAttributes:
-    description: Configuration of the security aspects of the Beacon. By default,
+    description: >-
+      Configuration of the security aspects of the Beacon. By default,
       a Beacon that does not declare the configuration settings would return `boolean`
       (true/false) responses, and only if the user is authenticated and explicitly
       authorized to access the Beacon resources. Although this is the safest set of
diff --git a/framework/src/responses/beaconBooleanResponse.yaml b/framework/src/responses/beaconBooleanResponse.yaml
index b68dc849..51226547 100644
--- a/framework/src/responses/beaconBooleanResponse.yaml
+++ b/framework/src/responses/beaconBooleanResponse.yaml
@@ -1,7 +1,10 @@
 $schema: https://json-schema.org/draft/2020-12/schema
 description: >-
-  Complete definition for a minimal response that provides *only* a `Boolean`
-  exists true|false answer.
+  Complete definition for a minimal response that provides *only* an aggregate
+  Boolean `"exists": true` or `"exists": false` answer to the query.  
+
+  Additional information - which should not consist of record-level information -
+  can be provided through `beaconHandovers`.  
 type: object
 properties:
   meta:
diff --git a/framework/src/responses/beaconCollectionsResponse.yaml b/framework/src/responses/beaconCollectionsResponse.yaml
index 93a35702..d6e55766 100644
--- a/framework/src/responses/beaconCollectionsResponse.yaml
+++ b/framework/src/responses/beaconCollectionsResponse.yaml
@@ -1,5 +1,9 @@
 $schema: https://json-schema.org/draft/2020-12/schema
-description: Beacon response that includes details about the collections in this Beacon.
+description: >-
+  A type of Beacon response that includes details about the **collections** in a
+  beacon. The types of collections are defined in each beacon's configuration;
+  if using the Beacon v2+ default model usually the types `dataset` and `cohort`
+  are supported.
 type: object
 properties:
   meta:
diff --git a/framework/src/responses/beaconConfigurationResponse.yaml b/framework/src/responses/beaconConfigurationResponse.yaml
index 28d38626..f4ee4995 100644
--- a/framework/src/responses/beaconConfigurationResponse.yaml
+++ b/framework/src/responses/beaconConfigurationResponse.yaml
@@ -1,8 +1,10 @@
 $schema: https://json-schema.org/draft/2020-12/schema
 type: object
 description: >-
-  Information about the Beacon. Aimed to Beacon clients like web pages
-  or Beacon networks.
+  The `beaconConfigurationResponse` returns information about configuration
+  parameters of a given beacon instance such as maturity or security attributes
+  or supported entry types. It is directed towards Beacon clients like web pages
+  or network aggregators.
 properties:
   meta:
     description: >-
diff --git a/framework/src/responses/beaconCountResponse.yaml b/framework/src/responses/beaconCountResponse.yaml
index 27d1dddb..1f03c9a6 100644
--- a/framework/src/responses/beaconCountResponse.yaml
+++ b/framework/src/responses/beaconCountResponse.yaml
@@ -1,7 +1,11 @@
 $schema: https://json-schema.org/draft/2020-12/schema
 description: >-
-  Complete definition for a response that does not include record level
-  details but provides `Boolean` and `count` information.
+  Complete definition for a minimal response that provides an aggregate Boolean
+  `"exists": true` or `"exists": false` answer to the query as well as the count
+  of the matched records.
+
+  Additional information - which should not consist of record-level information -
+  can be provided through `beaconHandovers`.  
 type: object
 properties:
   meta:
diff --git a/framework/src/responses/beaconEntryTypesResponse.yaml b/framework/src/responses/beaconEntryTypesResponse.yaml
index 16e5aef3..2919bf00 100644
--- a/framework/src/responses/beaconEntryTypesResponse.yaml
+++ b/framework/src/responses/beaconEntryTypesResponse.yaml
@@ -1,7 +1,9 @@
 $schema: https://json-schema.org/draft/2020-12/schema
 type: object
 description: >-
-  Response including a list of Entry types definitions.
+  The `beaconEntryTypesResponse` provides information about the entry types
+  served through a beacon, including their definitions and pointers to their
+  schemas.
 properties:
   meta:
     description: >-
diff --git a/framework/src/responses/beaconErrorResponse.yaml b/framework/src/responses/beaconErrorResponse.yaml
index e902a32f..eb1669d3 100644
--- a/framework/src/responses/beaconErrorResponse.yaml
+++ b/framework/src/responses/beaconErrorResponse.yaml
@@ -1,7 +1,8 @@
 $schema: https://json-schema.org/draft/2020-12/schema
 type: object
 description: >-
-  An unsuccessful operation.
+  A `beaconErrorResponse` denotes an unsuccessful operation, e.g. due to a missing
+  parameter or an invalid query. The response contains an error object.
 properties:
   meta:
     $ref: ./sections/beaconResponseMeta.yaml
diff --git a/framework/src/responses/beaconInfoResponse.yaml b/framework/src/responses/beaconInfoResponse.yaml
index 720015f8..01161086 100644
--- a/framework/src/responses/beaconInfoResponse.yaml
+++ b/framework/src/responses/beaconInfoResponse.yaml
@@ -1,8 +1,14 @@
 $schema: https://json-schema.org/draft/2020-12/schema
 type: object
 description: >-
-  Information about the Beacon. Aimed at Beacon clients like web pages
-  or Beacon networks.
+  The `beaconInfoResponse` provides metadata describing a Beacon instance, such
+  as its name, the organization responsible for the Beacon, contact information,
+  site logo and alternative URLs and importantly the beacon's API version. It is
+  based on the GA4GH `service-info` standard.
+
+  The content of the `beaconInfoResponse` can be used by clients such as web front
+  ends or beacon aggregators to evaluate potential access patterns and to display
+  information about the beacon.
 properties:
   meta:
     description: >-
diff --git a/framework/src/responses/beaconMapResponse.yaml b/framework/src/responses/beaconMapResponse.yaml
index 08a70e0a..c230024b 100644
--- a/framework/src/responses/beaconMapResponse.yaml
+++ b/framework/src/responses/beaconMapResponse.yaml
@@ -1,8 +1,10 @@
 $schema: https://json-schema.org/draft/2020-12/schema
 type: object
 description: >-
-  Information about the Beacon. Aimed to Beacon clients like web pages
-  or Beacon networks.
+  A `beaconMapResponse` provides information about the beacon instance such as the
+  different endpoints supported by this implementation of the Beacon API. This response
+  is aimed to allow Beacon clients such as web front ends and Beacon network aggregators
+  to evaluate which access patterns can be implemented against individual beacons.
 properties:
   meta:
     description: >-
diff --git a/framework/src/responses/beaconResultsetsResponse.yaml b/framework/src/responses/beaconResultsetsResponse.yaml
index 39601cbd..ff230fe8 100644
--- a/framework/src/responses/beaconResultsetsResponse.yaml
+++ b/framework/src/responses/beaconResultsetsResponse.yaml
@@ -1,5 +1,15 @@
 $schema: https://json-schema.org/draft/2020-12/schema
-description: Beacon response that includes record level details, grouped in Resultsets.
+description: >-
+  A `beaconResultsetsResponse` returns the results of a query against a beacon
+  or beacon aggregator. Beyond the `responseSummary` for overall matches the
+  response contains details about the matches in individual **collections** in
+  the beacon or beacon network. This type of response is required when serving
+  a request with a "record" level `responseGranularity`, and `beaconResultsets`
+  typically contain a list of records matched by the query.
+
+  The types of `beaconResultsets` objects are defined in the beacon's configuration;
+  e.g. if using the Beacon v2+ default model the types `dataset` and `cohort` are
+  supported as result sets.    
 type: object
 properties:
   meta:
diff --git a/models/json/beacon-v2-default-model/analyses/defaultSchema.json b/models/json/beacon-v2-default-model/analyses/defaultSchema.json
index 7def347a..b3ed73ee 100644
--- a/models/json/beacon-v2-default-model/analyses/defaultSchema.json
+++ b/models/json/beacon-v2-default-model/analyses/defaultSchema.json
@@ -2,17 +2,17 @@
     "$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"
             ],
@@ -20,20 +20,22 @@
             "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"
         },
@@ -41,30 +43,32 @@
             "$ref": "../common/info.json"
         },
         "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"
 }
\ No newline at end of file
diff --git a/models/src/beacon-v2-default-model/analyses/defaultSchema.yaml b/models/src/beacon-v2-default-model/analyses/defaultSchema.yaml
index 3022bb09..7622118f 100644
--- a/models/src/beacon-v2-default-model/analyses/defaultSchema.yaml
+++ b/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: ../common/info.yaml
 required: