JSON versions of last commit

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",

framework/json/configuration/entryTypeDefinition.json

@@ -1,8 +1,8 @@
 {
-    "$comment": "TO DO: The tagged parts should reference to `common/ontologizedElement.json`. But that configuration fails to validate. Further investigation is required, but should not affect the resulting schema.",
+    "$comment": "TODO: The tagged parts should reference to `common/ontologizedElement.json`. But that configuration fails to validate. Further investigation is required, but should not affect the resulting schema.'",
     "$schema": "https://json-schema.org/draft/2020-12/schema",
     "additionalProperties": true,
-    "description": "Definition of an element or entry type including the Beacon v2 required and suggested attributes. This schema purpose is to  describe each type of entities included in a Beacon, hence Beacon clients could have some metadata about such entities.\n\nThe `id` attribute is the key that should be used in other parts of the Beacon Model to allow Beacon clients to identify the different parts (e.g. endpoints, filteringTerms, request parameters, etc.) that fully describe an entry type.",
+    "description": "Definition of an element or entry type including the Beacon v2 required and suggested attributes. This schema purpose is to  describe each type of entities included in a Beacon, hence Beacon clients could have some metadata about such entities.  \nThe `id` attribute is the key that should be used in other parts of the Beacon Model to allow Beacon clients to identify the different parts (e.g. endpoints, filteringTerms, request parameters, etc.) that fully describe an entry type.",
     "properties": {
         "$schema": {
             "$ref": "../common/beaconCommonComponents.json#/$defs/$schema"

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",

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",

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",

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",

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",

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"

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",

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",

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",