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/configuration/entryTypeDefinition.yaml b/framework/src/configuration/entryTypeDefinition.yaml index 8f6fe509..ae7af921 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 97811e09..0cf7ac71 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 8b895ce6..948fd293 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 f083849b..f4c854fc 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 11e8b732..b1c54d52 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: