From 44ec3840f9580b6e0a607c628ee4ea4777d3057d Mon Sep 17 00:00:00 2001 From: Michael Baudis Date: Fri, 19 Jul 2024 10:43:33 +0200 Subject: [PATCH 1/3] update of inline descriptions in the analysis schema document * clarifications, rewording, example * no schema changes --- .../sections/beaconFilteringTermsResults.json | 32 +++++++++------ .../analyses/defaultSchema.json | 34 +++++++++------- .../beacon-v2-default-model/common/age.json | 4 +- .../common/ageRange.json | 4 +- .../common/complexValue.json | 4 +- .../genomicVariations/requestParameters.json | 6 +-- .../analyses/defaultSchema.yaml | 39 ++++++++++++------- 7 files changed, 75 insertions(+), 48 deletions(-) diff --git a/framework/json/responses/sections/beaconFilteringTermsResults.json b/framework/json/responses/sections/beaconFilteringTermsResults.json index 1755fb582..556d35993 100644 --- a/framework/json/responses/sections/beaconFilteringTermsResults.json +++ b/framework/json/responses/sections/beaconFilteringTermsResults.json @@ -21,6 +21,25 @@ ], "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": [ @@ -28,17 +47,6 @@ "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" -} +} \ No newline at end of file diff --git a/models/json/beacon-v2-default-model/analyses/defaultSchema.json b/models/json/beacon-v2-default-model/analyses/defaultSchema.json index e2fd84089..ef5646e01 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": "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" } \ No newline at end of file diff --git a/models/json/beacon-v2-default-model/common/age.json b/models/json/beacon-v2-default-model/common/age.json index e7f4a6c66..f6b941fde 100644 --- a/models/json/beacon-v2-default-model/common/age.json +++ b/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" -} +} \ No newline at end of file diff --git a/models/json/beacon-v2-default-model/common/ageRange.json b/models/json/beacon-v2-default-model/common/ageRange.json index 31fb79c76..1bb6ff693 100644 --- a/models/json/beacon-v2-default-model/common/ageRange.json +++ b/models/json/beacon-v2-default-model/common/ageRange.json @@ -12,8 +12,8 @@ } }, "required": [ - "end", - "start" + "start", + "end" ], "title": "AgeRange", "type": "object" diff --git a/models/json/beacon-v2-default-model/common/complexValue.json b/models/json/beacon-v2-default-model/common/complexValue.json index fd9993392..e60d69cb8 100644 --- a/models/json/beacon-v2-default-model/common/complexValue.json +++ b/models/json/beacon-v2-default-model/common/complexValue.json @@ -40,7 +40,9 @@ "type": "array" } }, - "required": [ "typedQuantities" ], + "required": [ + "typedQuantities" + ], "title": "Complex Value", "type": "object" } \ No newline at end of file diff --git a/models/json/beacon-v2-default-model/genomicVariations/requestParameters.json b/models/json/beacon-v2-default-model/genomicVariations/requestParameters.json index e469211f4..5831f13cf 100644 --- a/models/json/beacon-v2-default-model/genomicVariations/requestParameters.json +++ b/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" } -} +} \ 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 8eb87b5be..118bc5dd6 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: https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/framework/json/common/beaconCommonComponents.json#/definitions/Info required: From 98b899c3400d475c020a1adad24d7be122f1afe4 Mon Sep 17 00:00:00 2001 From: Michael Baudis Date: Mon, 11 Nov 2024 12:49:21 +0900 Subject: [PATCH 2/3] re-writing of some inline schema descriptions This commit re-writes some of the root descriptions of the response type schemas (mostly) into slightly more verbose and formatted texts. Besides the "documentation is good" paradigm one reason is the intended use of these for generating documentation pages - see the (under construction) rendering at https://bycon.progenetix.org/generated/beacon-responses/ --- .../beaconConfigurationSchema.yaml | 17 +++++++++++------ .../configuration/entryTypeDefinition.yaml | 19 +++++++++++-------- .../src/responses/beaconBooleanResponse.yaml | 7 +++++-- .../responses/beaconCollectionsResponse.yaml | 6 +++++- .../beaconConfigurationResponse.yaml | 6 ++++-- .../src/responses/beaconCountResponse.yaml | 8 ++++++-- .../responses/beaconEntryTypesResponse.yaml | 4 +++- .../src/responses/beaconErrorResponse.yaml | 3 ++- .../src/responses/beaconInfoResponse.yaml | 10 ++++++++-- .../src/responses/beaconMapResponse.yaml | 6 ++++-- .../responses/beaconResultsetsResponse.yaml | 12 +++++++++++- 11 files changed, 70 insertions(+), 28 deletions(-) diff --git a/framework/src/configuration/beaconConfigurationSchema.yaml b/framework/src/configuration/beaconConfigurationSchema.yaml index bcd6a64e4..6eaef9f28 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/configuration/entryTypeDefinition.yaml b/framework/src/configuration/entryTypeDefinition.yaml index 8f6fe509f..ae7af9215 100644 --- a/framework/src/configuration/entryTypeDefinition.yaml +++ b/framework/src/configuration/entryTypeDefinition.yaml @@ -1,14 +1,17 @@ $schema: https://json-schema.org/draft/2020-12/schema title: '' -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. + + The `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. type: object -$comment: 'TO DO: The tagged parts should reference to `common/ontologizedElement.json`. +$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.' properties: diff --git a/framework/src/responses/beaconBooleanResponse.yaml b/framework/src/responses/beaconBooleanResponse.yaml index 97811e09c..0cf7ac716 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 8b895ce6f..948fd2931 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 28d38626d..f4ee49954 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 f083849bd..f4c854fc6 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 16e5aef37..2919bf009 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 e902a32fa..eb1669d3a 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 720015f8f..011610860 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 08a70e0ad..c230024bb 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 11e8b732c..b1c54d52c 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: From cd1d46028ed237bc159dc2bf0935da3d73e981e1 Mon Sep 17 00:00:00 2001 From: Michael Baudis Date: Mon, 11 Nov 2024 19:41:40 +0900 Subject: [PATCH 3/3] JSON versions of last commit --- framework/json/configuration/beaconConfigurationSchema.json | 4 ++-- framework/json/configuration/entryTypeDefinition.json | 4 ++-- framework/json/responses/beaconBooleanResponse.json | 2 +- framework/json/responses/beaconCollectionsResponse.json | 2 +- framework/json/responses/beaconConfigurationResponse.json | 2 +- framework/json/responses/beaconCountResponse.json | 2 +- framework/json/responses/beaconEntryTypesResponse.json | 2 +- framework/json/responses/beaconErrorResponse.json | 2 +- framework/json/responses/beaconInfoResponse.json | 2 +- framework/json/responses/beaconMapResponse.json | 2 +- framework/json/responses/beaconResultsetsResponse.json | 2 +- 11 files changed, 13 insertions(+), 13 deletions(-) diff --git a/framework/json/configuration/beaconConfigurationSchema.json b/framework/json/configuration/beaconConfigurationSchema.json index 7b3b448ec..20c2e0556 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/configuration/entryTypeDefinition.json b/framework/json/configuration/entryTypeDefinition.json index ff8824678..cf9013827 100644 --- a/framework/json/configuration/entryTypeDefinition.json +++ b/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" diff --git a/framework/json/responses/beaconBooleanResponse.json b/framework/json/responses/beaconBooleanResponse.json index 8491ca4bd..5f1a24f46 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 6728e3342..afc01ea1d 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 ccd15687e..3551db860 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 9222ae90d..769f90894 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 2c2cc5514..d18fa8137 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 db7b0c0f0..3f01c1a16 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 a221e746c..5ed2651fe 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 d915b4a29..f2c059151 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 8efe9617a..cf6d1660b 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",