Removing filtering terms references specific to each entry type

README.md

@@ -8,7 +8,8 @@ This repository is a unified repository representing the different parts of the
 * [models](models)
 * Beacon v2 Documentation
     - authoritive source already in this repository [`/docs`](docs)
-    - rendered version through [here](https://beacon-project.io/beacon-v2/) (alternative address is [docs.genomebeacons.org](https://docs.genomebeacons.org))
+    - rendered version through [docs.genomebeacons.org](https://docs.genomebeacons.org)
+    - Please note that edits to the documentation (and document generation) happens on/from the [website-docs](https://github.com/ga4gh-beacon/beacon-v2/tree/website-docs) branch!
 
 As with other schema projects, here we separate between the schema source files (in `src`; JSON-Schema written in YAML) and the generated versions for referencing. The current setup allows already the direct referencing of the generated JSON schemas. Examples:
 
@@ -32,11 +33,24 @@ There is a set of tools in [`/bin`](./bin/) to facilitate the conversion. ATM, a
 
 ## 2.1.1
 
-*Released, October, 8, 2024*
-[Beacon-v2.1.1](https://github.com/ga4gh-beacon/beacon-v2/tree/5ea17fbd0d2ba533aa1e85f7271f9a2cc9be6794)
+*Released, December 13, 2024*
+[Beacon-v2.1.1](https://github.com/ga4gh-beacon/beacon-v2/tree/47af89c8fd199d2674e5ca7fb504815ebc145e63)
 
+* Updated links for make beacon compatible with upgraded VRS version 1.3
 * Changed uri for uri-template in Endpoint.singleEntryUrl
-
+* Moved info definition from beaconCommonComponents to an own common info schema
+* Added links to each of the schema version releases in the changelog
+* Improved inline documentation
+* Deleted includedConcepts from aCollectionOf
+* Removed the particular filteringTermsUrl entry related to a particular entry type
+* Moved default outside items object to the same items level
+* Defined content for default property in OpenAPI
+* Created examples for filters in OpenAPI
+* Moved default property in to the lowest level for securityLevels property in OpenAPI
+* Redefined includeResultsetResponses in OpenAPI
+* Defined content for responses in OpenAPI
+* Refactored definitions for $defs
+* Implemented new feature for filteringTerms values
 
 ## 2.1.0
 

bin/deref_schemas/individuals/defaultSchema.json

@@ -833,7 +833,7 @@
             ],
             "type": "string"
         },
-        "measures": {
+        "measurements": {
             "items": {
                 "$schema": "https://json-schema.org/draft/2020-12/schema",
                 "additionalProperties": true,

bin/deref_schemas/individuals/defaultSchema.yaml

@@ -590,7 +590,7 @@ properties:
       - XYY
       - OTHER_KARYOTYPE
     type: string
-  measures:
+  measurements:
     items:
       $schema: https://json-schema.org/draft/2020-12/schema
       additionalProperties: 1

bin/deref_schemas/obj/measures.yaml

@@ -1,5 +1,5 @@
 ---
-measures:
+measurements:
   items:
     $schema: https://json-schema.org/draft/2020-12/schema
     additionalProperties: 1

docs/schemas-md/beacon_terms.md

@@ -109,7 +109,7 @@
 * [locations](./obj/locations.md)
 * [measurements](./obj/measurements.md)
 * [measurementValue](./obj/measurementValue.md)
-* [measures](./obj/measures.md)
+* [measurements](./obj/measurements.md)
 * [memberId](./obj/memberId.md)
 * [members](./obj/members.md)
 * [modifiers](./obj/modifiers.md)

docs/schemas-md/individuals_defaultSchema.md

@@ -8,7 +8,7 @@
 | [info](./obj/info.md) | Placeholder to allow the Beacon to return any additional information that is necessary or could be of interest in relation to the query or the entry returned. It is recommended to encapsulate additional informations in this attribute instead of directly adding attributes at the same level than the others in order to avoid collision in the names of attributes in future versions of the specification. | object | NA | NA | NA|
 | [interventionsOrProcedures](./obj/interventionsOrProcedures.md) | Class describing a clinical procedure or intervention. Provenance: GA4GH Phenopackets v2 `Procedure` | array | [ageAtProcedure](./obj/ageAtProcedure.md), [bodySite](./obj/bodySite.md), [dateOfProcedure](./obj/dateOfProcedure.md), [procedureCode](./obj/procedureCode.md) | NA | NA|
 | [karyotypicSex](./obj/karyotypicSex.md) | The chromosomal sex of an individual represented from a selection of options. | string | NA | NA | UNKNOWN_KARYOTYPE, XX, XY, XO, XXY, XXX, XXYY, XXXY, XXXX, XYY, OTHER_KARYOTYPE|
-| [measures](./obj/measures.md) | Definition of a measurement class. Provenance: GA4GH Phenopackets v2 `Measurement` | array | [assayCode](./obj/assayCode.md), [date](./obj/date.md), [measurementValue](./obj/measurementValue.md), [notes](./obj/notes.md), [observationMoment](./obj/observationMoment.md), [procedure](./obj/procedure.md) | NA | NA|
+| [measurements](./obj/measurements.md) | Definition of a measurement class. Provenance: GA4GH Phenopackets v2 `Measurement` | array | [assayCode](./obj/assayCode.md), [date](./obj/date.md), [measurementValue](./obj/measurementValue.md), [notes](./obj/notes.md), [observationMoment](./obj/observationMoment.md), [procedure](./obj/procedure.md) | NA | NA|
 | [pedigrees](./obj/pedigrees.md) | Pedigree studies in which the individual is part of. | array | [disease](./obj/disease.md), [id](./obj/id.md), [members](./obj/members.md), [numSubjects](./obj/numSubjects.md) | NA | NA|
 | [phenotypicFeatures](./obj/phenotypicFeatures.md) | Used to describe a phenotype that characterizes the subject or biosample. | array | [evidence](./obj/evidence.md), [excluded](./obj/excluded.md), [featureType](./obj/featureType.md), [modifiers](./obj/modifiers.md), [notes](./obj/notes.md), [onset](./obj/onset.md), [resolution](./obj/resolution.md), [severity](./obj/severity.md) | NA | NA|
 | [sex](./obj/sex.md) | Sex of the individual. Value from NCIT General Qualifier (NCIT:C27993): 'unknown' (not assessed or not available) (NCIT:C17998), 'female' (NCIT:C16576), or 'male', (NCIT:C20197). | object | [id](./obj/id.md), [label](./obj/label.md) | `[{"id": "NCIT:C16576", "label": "female"}, {"id": "NCIT:C20197", "label": "male"}, {"id": "NCIT:C1799", "label": "unknown"}]` | NA|
@@ -65,7 +65,7 @@ These are examples extracted directly from the [GitHub repository](https://githu
 	        "label": "Slovenia"
 	    },
 	    "id": "Ind001",
-	    "measures": [
+	    "measurements": [
 	        {
 	            "assayCode": {
 	                "id": "LOINC:26515-7",

docs/schemas-md/obj/measures.md

@@ -1,3 +1,3 @@
 |Term | Description | Type | Properties | Example | Enum|
 | ---| ---| ---| ---| ---| --- |
-| measures | Definition of a measurement class. Provenance: GA4GH Phenopackets v2 `Measurement` | array | [assayCode](./assayCode.md), [date](./date.md), [measurementValue](./measurementValue.md), [notes](./notes.md), [observationMoment](./observationMoment.md), [procedure](./procedure.md) | NA | NA|
+| measurements | Definition of a measurement class. Provenance: GA4GH Phenopackets v2 `Measurement` | array | [assayCode](./assayCode.md), [date](./date.md), [measurementValue](./measurementValue.md), [notes](./notes.md), [observationMoment](./observationMoment.md), [procedure](./procedure.md) | NA | NA|

framework/json/configuration/examples/beaconConfiguration-example.json

@@ -17,7 +17,6 @@
             },
             "description": "A Dataset is a collection of records, like rows in a database or cards in a cardholder.",
             "endpoint": "/datasets",
-            "filteringTermsReference": "./datasets/filteringTerms.json",
             "id": "dataset",
             "name": "Dataset",
             "nonFilteredQueriesAllowed": true,
@@ -37,7 +36,6 @@
             },
             "description": "A generic entry type to allow testing and playing with the specification.",
             "endpoint": "./exampleEntries",
-            "filteringTermsReference": "./exampleEntry/filteringTerms.json",
             "id": "exampleEntry",
             "name": "Example Entry",
             "nonFilteredQueriesAllowed": false,

framework/json/configuration/examples/entriesCollectionDefinition_example.json

@@ -23,7 +23,6 @@
     },
     "description": "A Dataset is a collection of records, like rows in a database or cards in a cardholder.",
     "endpoint": "/datasets",
-    "filteringTermsReference": "./datasets/filteringTerms.json",
     "id": "dataset",
     "name": "Dataset",
     "ontologyTermForThisType": {

framework/json/responses/examples-fullDocuments/beaconConfigurationResponse-example.json

@@ -30,7 +30,6 @@
                 },
                 "description": "A Dataset is a collection of records, like rows in a database or cards in a cardholder.",
                 "endpoint": "/datasets",
-                "filteringTermsReference": "./datasets/filteringTerms.json",
                 "id": "dataset",
                 "name": "Dataset",
                 "ontologyTermForThisType": {
@@ -49,7 +48,6 @@
                 },
                 "description": "A generic entry type to allow testing and playing with the specification.",
                 "endpoint": "./exampleEntries",
-                "filteringTermsReference": "./exampleEntry/filteringTerms.json",
                 "id": "exampleEntry",
                 "name": "Example Entry",
                 "ontologyTermForThisType": {

framework/json/responses/examples-fullDocuments/beaconEntryTypesResponse-example.json

@@ -30,7 +30,6 @@
                 },
                 "description": "A Dataset is a collection of records, like rows in a database or cards in a cardholder.",
                 "endpoint": "/datasets",
-                "filteringTermsReference": "./datasets/filteringTerms.json",
                 "id": "dataset",
                 "name": "Dataset",
                 "ontologyTermForThisType": {
@@ -49,7 +48,6 @@
                 },
                 "description": "A generic entry type to allow testing and playing with the specification.",
                 "endpoint": "./exampleEntries",
-                "filteringTermsReference": "./exampleEntry/filteringTerms.json",
                 "id": "exampleEntry",
                 "name": "Example Entry",
                 "ontologyTermForThisType": {

framework/src/configuration/examples/beaconConfiguration-example.yaml

@@ -26,7 +26,6 @@ entryTypes:
       - id: exampleEntry
         name: Example entries
     endpoint: /datasets
-    filteringTermsReference: ./datasets/filteringTerms.json
     additionallySupportedSchemas: []
     nonFilteredQueriesAllowed: true
   exampleEntry:
@@ -43,6 +42,5 @@ entryTypes:
       referenceToSchemaDefinition: ./exampleEntry/defaultSchema.json
       schemaVersion: v.2
     endpoint: ./exampleEntries
-    filteringTermsReference: ./exampleEntry/filteringTerms.json
     additionallySupportedSchemas: []
     nonFilteredQueriesAllowed: false

framework/src/configuration/examples/entriesCollectionDefinition_example.yaml

@@ -16,7 +16,6 @@ aCollectionOf:
   - id: exampleEntry
     name: Example entries
 endpoint: /datasets
-filteringTermsReference: ./datasets/filteringTerms.json
 additionallySupportedSchemas:
   - id: ohdsi-atlas-cohort
     name: OHDSI ATLAS Cohort

framework/src/responses/examples-fullDocuments/beaconConfigurationResponse-example.yaml

@@ -34,7 +34,6 @@ response:
         - id: exampleEntry
           name: Example entries
       endpoint: /datasets
-      filteringTermsReference: ./datasets/filteringTerms.json
       additionallySupportedSchemas: []
     exampleEntry:
       id: exampleEntry
@@ -50,6 +49,5 @@ response:
         referenceToSchemaDefinition: ./exampleEntry/defaultSchema.json
         schemaVersion: v.2
       endpoint: ./exampleEntries
-      filteringTermsReference: ./exampleEntry/filteringTerms.json
       additionallySupportedSchemas: []
 info: {}

framework/src/responses/examples-fullDocuments/beaconEntryTypesResponse-example.yaml

@@ -26,7 +26,6 @@ response:
         - id: exampleEntry
           name: Example entries
       endpoint: /datasets
-      filteringTermsReference: ./datasets/filteringTerms.json
       additionallySupportedSchemas: []
     exampleEntry:
       id: exampleEntry
@@ -42,6 +41,5 @@ response:
         referenceToSchemaDefinition: ./exampleEntry/defaultSchema.json
         schemaVersion: v.2
       endpoint: ./exampleEntries
-      filteringTermsReference: ./exampleEntry/filteringTerms.json
       additionallySupportedSchemas: []
 info: {}

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

@@ -30,7 +30,7 @@
                 "in": "query",
                 "name": "includeResultsetResponses",
                 "schema": {
-                    "$ref": "https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/framework/json/common/beaconCommonComponents.json#/definitions/IncludeResultsetResponses"
+                    "$ref": "https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/framework/json/common/beaconCommonComponents.json#/$defs/IncludeResultsetResponses"
                 }
             },
             "limit": {

models/json/beacon-v2-default-model/biosamples/endpoints.json

@@ -40,7 +40,7 @@
                 "in": "query",
                 "name": "includeResultsetResponses",
                 "schema": {
-                    "$ref": "https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/framework/json/common/beaconCommonComponents.json#/definitions/IncludeResultsetResponses"
+                    "$ref": "https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/framework/json/common/beaconCommonComponents.json#/$defs/IncludeResultsetResponses"
                 }
             },
             "limit": {

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

@@ -273,6 +273,9 @@
             "description": "Inclusion criteria used for defining the cohort. It is assumed that all cohort participants will match such criteria.",
             "type": "object"
         },
+        "info": {
+            "$ref": "../common/info.json"
+        },
         "name": {
             "description": "Name of the cohort. For `user-defined` this field could be generated upon the query, e.g. a value that is a concatenationor some representation of the user query.",
             "examples": [

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

@@ -0,0 +1,6 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "description": "Placeholder to allow the Beacon models to return additional information. It is recommended to encapsulate additional informations in this attribute instead of directly adding attributes at the schema's root level in order to avoid collision in the names of attributes in future versions of the specification.",
+    "title": "Info",
+    "type": "object"
+}

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

@@ -1,7 +1,7 @@
 {
     "$comments": "If using an ontology class the use of NCIT Age Group ontology term (NCIT:C20587) descendants is recommended.",
     "$schema": "https://json-schema.org/draft/2020-12/schema",
-    "description": "Definition of a wrapper for various time descriptors. This follows the Phenopackets structure https://github.com/phenopackets/phenopacket-schema/blob/v2/docs/time-element.rst",
+    "description": "Definition of a wrapper for various time descriptors. This follows the\nPhenopackets structure https://github.com/phenopackets/phenopacket-schema/blob/v2/docs/time-element.rst",
     "oneOf": [
         {
             "$ref": "./age.json"
@@ -23,5 +23,8 @@
         }
     ],
     "title": "TimeElement",
-    "type": "object"
+    "type": [
+        "object",
+        "string"
+    ]
 }

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

@@ -540,6 +540,9 @@
         "identifiers": {
             "$ref": "#/$defs/Identifiers"
         },
+        "info": {
+            "$ref": "../common/info.json"
+        },
         "molecularAttributes": {
             "$ref": "#/$defs/MolecularAttributes"
         },

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

@@ -92,7 +92,7 @@
                 "in": "query",
                 "name": "includeResultsetResponses",
                 "schema": {
-                    "$ref": "https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/framework/json/common/beaconCommonComponents.json#/definitions/IncludeResultsetResponses"
+                    "$ref": "https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/framework/json/common/beaconCommonComponents.json#/$defs/IncludeResultsetResponses"
                 }
             },
             "limit": {

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

@@ -43,7 +43,7 @@
             "$ref": "../common/commonDefinitions.json#/$defs/KaryotypicSex",
             "description": "The chromosomal sex of an individual represented from a selection of options."
         },
-        "measures": {
+        "measurements": {
             "items": {
                 "$ref": "../common/measurement.json"
             },

models/json/beacon-v2-default-model/individuals/endpoints.json

@@ -30,7 +30,7 @@
                 "in": "query",
                 "name": "includeResultsetResponses",
                 "schema": {
-                    "$ref": "https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/framework/json/common/beaconCommonComponents.json#/definitions/IncludeResultsetResponses"
+                    "$ref": "https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/framework/json/common/beaconCommonComponents.json#/$defs/IncludeResultsetResponses"
                 }
             },
             "limit": {

models/json/beacon-v2-default-model/individuals/examples/individual-MID-example.json

@@ -32,7 +32,7 @@
         "label": "Slovenia"
     },
     "id": "Ind001",
-    "measures": [
+    "measurements": [
         {
             "assayCode": {
                 "id": "LOINC:26515-7",

models/json/beacon-v2-default-model/runs/endpoints.json

@@ -38,7 +38,7 @@
                 "in": "query",
                 "name": "includeResultsetResponses",
                 "schema": {
-                    "$ref": "https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/framework/json/common/beaconCommonComponents.json#/definitions/IncludeResultsetResponses"
+                    "$ref": "https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/framework/json/common/beaconCommonComponents.json#/$defs/IncludeResultsetResponses"
                 }
             },
             "individualId": {

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

@@ -172,7 +172,7 @@ components:
       name: includeResultsetResponses
       in: query
       schema:
-        $ref: https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/framework/json/common/beaconCommonComponents.json#/definitions/IncludeResultsetResponses
+        $ref: https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/framework/json/common/beaconCommonComponents.json#/$defs/IncludeResultsetResponses
     entryId:
       name: id
       in: path

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

@@ -161,6 +161,7 @@ properties:
     example: {}
   info:
     $ref: ../common/info.yaml
+
 required:
   - id
   - biosampleStatus

models/src/beacon-v2-default-model/biosamples/endpoints.yaml

@@ -262,7 +262,7 @@ components:
       name: includeResultsetResponses
       in: query
       schema:
-        $ref: https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/framework/json/common/beaconCommonComponents.json#/definitions/IncludeResultsetResponses
+        $ref: https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/framework/json/common/beaconCommonComponents.json#/$defs/IncludeResultsetResponses
     entryId:
       name: id
       in: path

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

@@ -75,6 +75,9 @@ properties:
     type: array
     items:
       $ref: '#/$defs/CollectionEvent'
+  info:
+    $ref: ../common/info.yaml
+
 $defs:
   CollectionEvent:
     description: TBD

models/src/beacon-v2-default-model/common/info.yaml

@@ -0,0 +1,9 @@
+$schema: https://json-schema.org/draft/2020-12/schema
+title: Info
+description: >-
+  Placeholder to allow the Beacon models to return additional information.
+  It is recommended to encapsulate additional informations in this attribute
+  instead of directly adding attributes at the schema's root level in
+  order to avoid collision in the names of attributes in future versions of
+  the specification.
+type: object

models/src/beacon-v2-default-model/common/timeElement.yaml

@@ -1,8 +1,11 @@
 $schema: https://json-schema.org/draft/2020-12/schema
 title: TimeElement
-description: Definition of a wrapper for various time descriptors. This follows the
+description: |-
+  Definition of a wrapper for various time descriptors. This follows the
   Phenopackets structure https://github.com/phenopackets/phenopacket-schema/blob/v2/docs/time-element.rst
-type: object
+type:
+  - object
+  - string
 $comments: If using an ontology class the use of NCIT Age Group ontology term (NCIT:C20587)
   descendants is recommended.
 oneOf:

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

@@ -39,11 +39,12 @@ properties:
       3986 format).
     examples:
       - https://example.org/wiki/Main_Page
-  info:
-    $ref: ../common/info.yaml
   dataUseConditions:
     description: Data use conditions applying to this dataset.
     $ref: ../common/dataUseConditions.yaml
+  info:
+    $ref: ../common/info.yaml
+
 required:
   - id
   - name

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

@@ -42,6 +42,9 @@ properties:
     type: array
     items:
       $ref: '#/$defs/FrequencyInPopulations'
+  info:
+    $ref: ../common/info.yaml
+
 $defs:
   LegacyVariation:
     type: object