Merge pull request #212 from ga4gh-beacon/schema-urgent-fixes-filteringTerms-scope-definitions

filteringTerms scope definition modification

Author: costero-e

framework/json/requests/filteringTerms.json

@@ -1,7 +1,7 @@
 {
     "$defs": {
         "AlphanumericFilter": {
-            "description": "Filter results based on operators and values applied to alphanumeric fields.",
+            "description": "Filter results based on operators and values applied to alphanumeric\nfields.",
             "properties": {
                 "id": {
                     "description": "Field identfier to be queried.",
@@ -23,8 +23,10 @@
                     "type": "string"
                 },
                 "scope": {
-                    "description": "The entry type to which the filter applies",
-                    "example": "individuals",
+                    "description": "The entry type in the model to which the filter should be applied. It\nis good practice to use unanimous `id` values (e.g. `ageAtDiagnosis`\ninstead of `age`) and avoid the use of the `scope` parameter.",
+                    "examples": [
+                        "individuals"
+                    ],
                     "type": "string"
                 },
                 "value": {
@@ -49,8 +51,10 @@
                     "type": "string"
                 },
                 "scope": {
-                    "description": "The entry type to which the filter applies",
-                    "example": "individuals",
+                    "description": "The entry type in the model to which the filter should be applied.",
+                    "examples": [
+                        "individuals"
+                    ],
                     "type": "string"
                 }
             },
@@ -86,8 +90,10 @@
                     "type": "boolean"
                 },
                 "scope": {
-                    "description": "The entry type to which the filter applies",
-                    "example": "biosamples",
+                    "description": "The entry type in the model to which the filter should be applied. For\nexample, the use of `NCIT:C4013` (Malignant Head and Neck Neoplasm) can\nw/o specified scope mean both \"match cancer samples\" or \"match individuals\"\nwith the disease\" which - in the case of individuals - could then lead\nto matching germline and cancer variants while a scope of `biosamples`\nwould limit the response to variants observed in the cancer tissue.\nNote: It is good practice to avoid ambiguous terms, _i.e._ use different\nvocabularies for different entry types.",
+                    "examples": [
+                        "biosamples"
+                    ],
                     "type": "string"
                 },
                 "similarity": {

framework/src/requests/filteringTerms.yaml

@@ -45,10 +45,20 @@ $defs:
           of 'high', 'medium' and 'low' similarity.
       scope:
         type: string
-        description: The entry type to which the filter applies
-        example: biosamples
+        description: |-
+          The entry type in the model to which the filter should be applied. For
+          example, the use of `NCIT:C4013` (Malignant Head and Neck Neoplasm) can
+          w/o specified scope mean both "match cancer samples" or "match individuals"
+          with the disease" which - in the case of individuals - could then lead
+          to matching germline and cancer variants while a scope of `biosamples`
+          would limit the response to variants observed in the cancer tissue.
+          Note: It is good practice to avoid ambiguous terms, _i.e._ use different
+          vocabularies for different entry types.
+        examples:
+          - biosamples
   AlphanumericFilter:
-    description: Filter results based on operators and values applied to alphanumeric
+    description: |-
+      Filter results based on operators and values applied to alphanumeric
       fields.
     type: object
     required:
@@ -81,8 +91,12 @@ $defs:
         example: P70Y
       scope:
         type: string
-        description: The entry type to which the filter applies
-        example: individuals
+        description: |-
+          The entry type in the model to which the filter should be applied. It
+          is good practice to use unanimous `id` values (e.g. `ageAtDiagnosis`
+          instead of `age`) and avoid the use of the `scope` parameter.
+        examples:
+          - individuals
   CustomFilter:
     type: object
     description: Filter results to include records that contain a custom term defined
@@ -96,6 +110,8 @@ $defs:
         example: demographic.ethnicity:asian
       scope:
         type: string
-        description: The entry type to which the filter applies
-        example: individuals
+        description: |-
+          The entry type in the model to which the filter should be applied.
+        examples:
+          - individuals
 additionalProperties: true