From a6fe8ada50c47429b0b5fa6406cf2b3766231a1e Mon Sep 17 00:00:00 2001
From: Michael Baudis <m@baud.is>
Date: Wed, 17 Jul 2024 13:47:28 +0200
Subject: [PATCH] Cleanup of descriptions in endpoints files

The OpenAPI `endpoints` files included a number of leftover or potentially misleading descripions, e.g.:
* "get a list of..." as description for responses, although responses depend on granularity and delivered in different Beacon response schemas
* frequent use of "variant" instead "variation"
* some wrong labels (e.g. C&P errors or leftover "examples" response)

Additionally the leftover commented lines from the yamlerRunner have been removed.
---
 bin/yamlerRunner.sh                           | 15 -------
 .../analyses/endpoints.json                   | 12 +++---
 .../biosamples/endpoints.json                 | 24 +++++------
 .../cohorts/endpoints.json                    | 12 +++---
 .../datasets/endpoints.json                   | 18 ++++----
 .../genomicVariations/endpoints.json          | 24 +++++------
 .../individuals/endpoints.json                | 12 +++---
 .../runs/endpoints.json                       | 20 ++++-----
 .../analyses/endpoints.yaml                   | 20 +++++----
 .../biosamples/endpoints.yaml                 | 42 +++++++++++--------
 .../cohorts/endpoints.yaml                    | 20 +++++----
 .../datasets/endpoints.yaml                   | 30 ++++++++-----
 .../genomicVariations/endpoints.yaml          | 40 ++++++++++--------
 .../individuals/endpoints.yaml                | 20 +++++----
 .../runs/endpoints.yaml                       | 31 ++++++++------
 15 files changed, 181 insertions(+), 159 deletions(-)

diff --git a/bin/yamlerRunner.sh b/bin/yamlerRunner.sh
index a7821edfa..f6c16395b 100755
--- a/bin/yamlerRunner.sh
+++ b/bin/yamlerRunner.sh
@@ -1,28 +1,13 @@
 BASEDIR=$(dirname $0)
 UNITYPATH=$BASEDIR/..
-
-# initial conversion from separate schemas
-# DEPRECATED
-# BEACONMODELPATH=$BASEDIR/../../beacon-v2-Models/BEACON-V2-Model
-# BEACONFRAMEWORKPATH=$BASEDIR/../../beacon-framework-v2
-
 BEACONMODELNAME=beacon-v2-default-model
 
-# for UPSTREAM in $BEACONMODELPATH $BEACONFRAMEWORKPATH
-# do
-# 	echo "pulling $UPSTREAM"
-# 	git -C $UPSTREAM pull
-# done
-
 for KIND in src json
 do
 	mkdir -p $UNITYPATH/models/$KIND/$BEACONMODELNAME
 	mkdir -p $UNITYPATH/framework/$KIND	
 done
 
-# $BASEDIR/beaconYamler.py -i $BEACONMODELPATH -t json -x yaml -o $UNITYPATH/models/src/$BEACONMODELNAME
-# $BASEDIR/beaconYamler.py -i $BEACONFRAMEWORKPATH -t json -x yaml -o $UNITYPATH/framework/src
-
 # recurring conversion from the source files to the exported versions
 $BASEDIR/beaconYamler.py -i $UNITYPATH/models/src/$BEACONMODELNAME -t yaml -x json -o $UNITYPATH/models/json/$BEACONMODELNAME
 $BASEDIR/beaconYamler.py -i $UNITYPATH/framework/src -t yaml -x json -o $UNITYPATH/framework/json
diff --git a/models/json/beacon-v2-default-model/analyses/endpoints.json b/models/json/beacon-v2-default-model/analyses/endpoints.json
index 570d7201d..62387053c 100644
--- a/models/json/beacon-v2-default-model/analyses/endpoints.json
+++ b/models/json/beacon-v2-default-model/analyses/endpoints.json
@@ -91,7 +91,7 @@
     "paths": {
         "/analyses": {
             "get": {
-                "description": "Get a list of bioinformatics analysis",
+                "description": "Get a Beacon response for bioinformatics analyses",
                 "operationId": "getAnalyses",
                 "parameters": [
                     {
@@ -123,7 +123,7 @@
                 ]
             },
             "post": {
-                "description": "Get a list of bioinformatics analysis",
+                "description": "Get a Beacon response for bioinformatics analyses",
                 "operationId": "postAnalysesRequest",
                 "requestBody": {
                     "content": {
@@ -207,8 +207,8 @@
         },
         "/analyses/{id}/g_variants": {
             "get": {
-                "description": "Get the list of variants instances for one bioinformatics analysis, identified by its (unique) 'id'",
-                "operationId": "getOneAnalysisVariants",
+                "description": "Get a *genomic variations* response for one bioinformatics analysis, identified by its (unique) 'id'",
+                "operationId": "getOneAnalysisVariationsRequest",
                 "parameters": [
                     {
                         "$ref": "#/components/parameters/requestedSchema"
@@ -239,8 +239,8 @@
                 }
             ],
             "post": {
-                "description": "Get the list of variants instances for one bioinformatics analysis, identified by its (unique) 'id'",
-                "operationId": "postOneAnalysisVariantsRequest",
+                "description": "Get a *genomic variations* response for one bioinformatics analysis, identified by its (unique) 'id'",
+                "operationId": "postOneAnalysisVariationsRequest",
                 "requestBody": {
                     "content": {
                         "application/json": {
diff --git a/models/json/beacon-v2-default-model/biosamples/endpoints.json b/models/json/beacon-v2-default-model/biosamples/endpoints.json
index 533d5ceda..c9c94bfa5 100644
--- a/models/json/beacon-v2-default-model/biosamples/endpoints.json
+++ b/models/json/beacon-v2-default-model/biosamples/endpoints.json
@@ -95,7 +95,7 @@
     "paths": {
         "/biosamples": {
             "get": {
-                "description": "Get a list of biosamples",
+                "description": "Get a Beacon response for biosamples",
                 "operationId": "getBiosamples",
                 "parameters": [
                     {
@@ -127,7 +127,7 @@
                 ]
             },
             "post": {
-                "description": "Get a list of biosamples",
+                "description": "Get a Beacon response for biosamples",
                 "operationId": "postBiosamplesRequest",
                 "requestBody": {
                     "content": {
@@ -204,8 +204,8 @@
         },
         "/biosamples/{id}/analyses": {
             "get": {
-                "description": "Get the analysis list from one biosample, identified by its (unique) 'id'",
-                "operationId": "getOneBiosampleAnalysis",
+                "description": "Get an *analyses* response from one biosample, identified by its (unique) 'id'",
+                "operationId": "getOneBiosampleAnalyses",
                 "parameters": [
                     {
                         "$ref": "#/components/parameters/requestedSchema"
@@ -236,8 +236,8 @@
                 }
             ],
             "post": {
-                "description": "Get the analysis list from one biosample, identified by its (unique) 'id'",
-                "operationId": "postOneBiosampleAnalysis",
+                "description": "Get an *analyses* response from one biosample, identified by its (unique) 'id'",
+                "operationId": "postOneBiosampleAnalyses",
                 "requestBody": {
                     "content": {
                         "application/json": {
@@ -264,8 +264,8 @@
         },
         "/biosamples/{id}/g_variants": {
             "get": {
-                "description": "Get the genomic variants list from one biosample, identified by its (unique) 'id'",
-                "operationId": "getOneBiosampleGenomicVariants",
+                "description": "Get a *genomic variations* response from one biosample, identified by its (unique) 'id'",
+                "operationId": "getOneBiosampleGenomicVariations",
                 "parameters": [
                     {
                         "$ref": "#/components/parameters/requestedSchema"
@@ -296,8 +296,8 @@
                 }
             ],
             "post": {
-                "description": "Get the genomic variants list from one biosample, identified by its (unique) 'id'",
-                "operationId": "postOneBiosampleGenomicVariants",
+                "description": "Get a *genomic variations* response from one biosample, identified by its (unique) 'id'",
+                "operationId": "postOneBiosampleGenomicVariations",
                 "requestBody": {
                     "content": {
                         "application/json": {
@@ -324,7 +324,7 @@
         },
         "/biosamples/{id}/runs": {
             "get": {
-                "description": "Get the runs list from one biosample, identified by its (unique) 'id'",
+                "description": "Get a *runs* response from one biosample, identified by its (unique) 'id'",
                 "operationId": "getOneBiosampleRuns",
                 "parameters": [
                     {
@@ -363,7 +363,7 @@
                 }
             ],
             "post": {
-                "description": "Get the runs list from one biosample, identified by its (unique) 'id'",
+                "description": "Get a *runs* response from one biosample, identified by its (unique) 'id'",
                 "operationId": "postOneBiosampleRuns",
                 "requestBody": {
                     "content": {
diff --git a/models/json/beacon-v2-default-model/cohorts/endpoints.json b/models/json/beacon-v2-default-model/cohorts/endpoints.json
index 1e36b7462..588b0746e 100644
--- a/models/json/beacon-v2-default-model/cohorts/endpoints.json
+++ b/models/json/beacon-v2-default-model/cohorts/endpoints.json
@@ -108,7 +108,7 @@
     "paths": {
         "/cohorts": {
             "get": {
-                "description": "Get a list of cohorts",
+                "description": "Get a Beacon *cohorts* response",
                 "operationId": "getCohorts",
                 "parameters": [
                     {
@@ -137,7 +137,7 @@
                 ]
             },
             "post": {
-                "description": "Get a list of cohorts",
+                "description": "Get a Beacon *cohorts* response",
                 "operationId": "postCohortsRequest",
                 "requestBody": {
                     "content": {
@@ -219,7 +219,7 @@
         },
         "/cohorts/{id}/filtering_terms": {
             "get": {
-                "description": "Get the list of filtering terms that could be used with a given cohort, identified by its (unique) 'id'",
+                "description": "Get a response about the *filtering terms* that could be used with a given cohort, identified by its (unique) 'id'",
                 "operationId": "getOneCohortFilteringTerms",
                 "parameters": [
                     {
@@ -255,7 +255,7 @@
                 }
             ],
             "post": {
-                "description": "Get the list of filtering terms that could be used with a given cohort, identified by its (unique) 'id'",
+                "description": "Get a response about the *filtering terms* that could be used with a given cohort, identified by its (unique) 'id'",
                 "operationId": "postOneCohortFilteringTerms",
                 "requestBody": {
                     "content": {
@@ -290,7 +290,7 @@
         },
         "/cohorts/{id}/individuals": {
             "get": {
-                "description": "Get the individuals from one cohort, identified by its (unique) 'id'",
+                "description": "Get an *individuals* response for one cohort, identified by its (unique) 'id'",
                 "operationId": "getOneCohortIndividuals",
                 "parameters": [
                     {
@@ -322,7 +322,7 @@
                 }
             ],
             "post": {
-                "description": "Get the individuals from one cohort, identified by its (unique) 'id'",
+                "description": "Get an *individuals* response for one cohort, identified by its (unique) 'id'",
                 "operationId": "postOneCohortEntries",
                 "requestBody": {
                     "content": {
diff --git a/models/json/beacon-v2-default-model/datasets/endpoints.json b/models/json/beacon-v2-default-model/datasets/endpoints.json
index 3fdc832a4..56079f6e2 100644
--- a/models/json/beacon-v2-default-model/datasets/endpoints.json
+++ b/models/json/beacon-v2-default-model/datasets/endpoints.json
@@ -135,7 +135,7 @@
                 ]
             },
             "post": {
-                "description": "Get a list of datasets",
+                "description": "Get a Beacon *datasets* response",
                 "operationId": "postDatasetsRequest",
                 "requestBody": {
                     "content": {
@@ -217,7 +217,7 @@
         },
         "/datasets/{id}/biosamples": {
             "get": {
-                "description": "Get the biosamples list from one dataset, identified by its (unique) 'id'",
+                "description": "Get a *biosamples* response for one dataset, identified by its (unique) 'id'",
                 "operationId": "getOneDatasetBiosamples",
                 "parameters": [
                     {
@@ -249,7 +249,7 @@
                 }
             ],
             "post": {
-                "description": "Get the biosamples list from one dataset, identified by its (unique) 'id'",
+                "description": "Get a *biosamples* response for one dataset, identified by its (unique) 'id'",
                 "operationId": "postOneDatasetBiosamples",
                 "requestBody": {
                     "content": {
@@ -277,7 +277,7 @@
         },
         "/datasets/{id}/filtering_terms": {
             "get": {
-                "description": "Get the list of filtering terms that could be used with a given dataset, identified by its (unique) 'id'",
+                "description": "Get a response about the *filtering terms* that could be used with a given dataset, identified by its (unique) 'id'",
                 "operationId": "getOneDatasetFilteringTerms",
                 "parameters": [
                     {
@@ -313,7 +313,7 @@
                 }
             ],
             "post": {
-                "description": "Get the list of filtering terms that could be used with a given dataset, identified by its (unique) 'id'",
+                "description": "Get a response about the *filtering terms* that could be used with a given dataset, identified by its (unique) 'id'",
                 "operationId": "postOneDatasetFilteringTerms",
                 "requestBody": {
                     "content": {
@@ -348,7 +348,7 @@
         },
         "/datasets/{id}/g_variants": {
             "get": {
-                "description": "Get the genomic variants list from one dataset, identified by its (unique) 'id'",
+                "description": "Get a *genomic variations* response for one dataset, identified by its (unique) 'id'",
                 "operationId": "getOneDatasetEntries",
                 "parameters": [
                     {
@@ -380,7 +380,7 @@
                 }
             ],
             "post": {
-                "description": "Get the genomic variants list from one dataset, identified by its (unique) 'id'",
+                "description": "Get a *genomic variations* response for one dataset, identified by its (unique) 'id'",
                 "operationId": "postOneDatasetEntries",
                 "requestBody": {
                     "content": {
@@ -408,7 +408,7 @@
         },
         "/datasets/{id}/individuals": {
             "get": {
-                "description": "Get the individuals list from one dataset, identified by its (unique) 'id'",
+                "description": "Get an *individuals* response for one dataset, identified by its (unique) 'id'",
                 "operationId": "getOneDatasetIndividuals",
                 "parameters": [
                     {
@@ -440,7 +440,7 @@
                 }
             ],
             "post": {
-                "description": "Get the biosamples list from one dataset, identified by its (unique) 'id'",
+                "description": "Get an *individuals* response for one dataset, identified by its (unique) 'id'",
                 "operationId": "postOneDatasetIndividuals",
                 "requestBody": {
                     "content": {
diff --git a/models/json/beacon-v2-default-model/genomicVariations/endpoints.json b/models/json/beacon-v2-default-model/genomicVariations/endpoints.json
index e9101f04f..4ba82ba62 100644
--- a/models/json/beacon-v2-default-model/genomicVariations/endpoints.json
+++ b/models/json/beacon-v2-default-model/genomicVariations/endpoints.json
@@ -193,8 +193,8 @@
     "paths": {
         "/g_variants": {
             "get": {
-                "description": "Get a list of example entries",
-                "operationId": "getExampleEntries",
+                "description": "Get a Beacon response for genomic variations",
+                "operationId": "getGenomicVariations",
                 "parameters": [
                     {
                         "$ref": "#/components/parameters/requestedSchema"
@@ -258,8 +258,8 @@
                 ]
             },
             "post": {
-                "description": "Get a list of example entries",
-                "operationId": "postExampleEntriesRequest",
+                "description": "Get a Beacon response for genomic variations",
+                "operationId": "postGenomicVariationsRequest",
                 "requestBody": {
                     "content": {
                         "application/json": {
@@ -335,8 +335,8 @@
         },
         "/g_variants/{id}/biosamples": {
             "get": {
-                "description": "Get the biosamples list from one genomic variant, identified by its (unique) 'id'",
-                "operationId": "getOneGenomicVariantBiosamples",
+                "description": "Get a *biosamples* response from one genomic variant, identified by its (unique) 'id'",
+                "operationId": "getOneGenomicVariationBiosamples",
                 "parameters": [
                     {
                         "$ref": "#/components/parameters/requestedSchema"
@@ -367,8 +367,8 @@
                 }
             ],
             "post": {
-                "description": "Get the biosamples list from one genomic variant, identified by its (unique) 'id'",
-                "operationId": "postOneGenomicVariantBiosamples",
+                "description": "Get a *biosamples* response from one genomic variant, identified by its (unique) 'id'",
+                "operationId": "postOneGenomicVariationBiosamples",
                 "requestBody": {
                     "content": {
                         "application/json": {
@@ -395,8 +395,8 @@
         },
         "/g_variants/{id}/individuals": {
             "get": {
-                "description": "Get the individuals list from one genomic variant, identified by its (unique) 'id'",
-                "operationId": "getOneGenomicVariantIndividuals",
+                "description": "Get an *individuals* response from one genomic variant, identified by its (unique) 'id'",
+                "operationId": "getOneGenomicVariationIndividuals",
                 "parameters": [
                     {
                         "$ref": "#/components/parameters/requestedSchema"
@@ -427,8 +427,8 @@
                 }
             ],
             "post": {
-                "description": "Get the biosamples list from one genomic variant, identified by its (unique) 'id'",
-                "operationId": "postOneGenomicVariantIndividuals",
+                "description": "Get an *individuals* response from one genomic variant, identified by its (unique) 'id'",
+                "operationId": "postOneGenomicVariationIndividuals",
                 "requestBody": {
                     "content": {
                         "application/json": {
diff --git a/models/json/beacon-v2-default-model/individuals/endpoints.json b/models/json/beacon-v2-default-model/individuals/endpoints.json
index 32898cb17..9da047ddd 100644
--- a/models/json/beacon-v2-default-model/individuals/endpoints.json
+++ b/models/json/beacon-v2-default-model/individuals/endpoints.json
@@ -123,7 +123,7 @@
                 ]
             },
             "post": {
-                "description": "Get a list of example entries",
+                "description": "Get a Beacon response for individuals",
                 "operationId": "postIndividualsRequest",
                 "requestBody": {
                     "content": {
@@ -238,7 +238,7 @@
                 }
             ],
             "post": {
-                "description": "Get details about one Individual, identified by its (unique) 'id'",
+                "description": "Get details about one individual, identified by its (unique) 'id'",
                 "operationId": "postOneIndividual",
                 "requestBody": {
                     "content": {
@@ -266,7 +266,7 @@
         },
         "/individuals/{id}/biosamples": {
             "get": {
-                "description": "Get the biosamples list from one individual, identified by its (unique) 'id'",
+                "description": "Get a *biosamples* response for one individual, identified by its (unique) 'id'",
                 "operationId": "getOneIndividualBiosamples",
                 "parameters": [
                     {
@@ -298,7 +298,7 @@
                 }
             ],
             "post": {
-                "description": "Get the biosamples list from one individual, identified by its (unique) 'id'",
+                "description": "Get a *biosamples* response for one individual, identified by its (unique) 'id'",
                 "operationId": "postOneIndividualBiosamples",
                 "requestBody": {
                     "content": {
@@ -326,7 +326,7 @@
         },
         "/individuals/{id}/g_variants": {
             "get": {
-                "description": "Get the genomic variants list from one individual, identified by its (unique) 'id'",
+                "description": "Get a *genomic variations* response for one individual, identified by its (unique) 'id'",
                 "operationId": "getOneIndividualGenomicVariants",
                 "parameters": [
                     {
@@ -358,7 +358,7 @@
                 }
             ],
             "post": {
-                "description": "Get the genomic variants list from one individual, identified by its (unique) 'id'",
+                "description": "Get a *genomic variations* response for one individual, identified by its (unique) 'id'",
                 "operationId": "potOneIndividualGenomicVariants",
                 "requestBody": {
                     "content": {
diff --git a/models/json/beacon-v2-default-model/runs/endpoints.json b/models/json/beacon-v2-default-model/runs/endpoints.json
index b5084bba7..06283d53b 100644
--- a/models/json/beacon-v2-default-model/runs/endpoints.json
+++ b/models/json/beacon-v2-default-model/runs/endpoints.json
@@ -107,7 +107,7 @@
     "paths": {
         "/runs": {
             "get": {
-                "description": "Get a list of sequencing runs",
+                "description": "Get a Beacon response for experimental runs",
                 "operationId": "getRuns",
                 "parameters": [
                     {
@@ -139,7 +139,7 @@
                 ]
             },
             "post": {
-                "description": "Get a list of sequencing runs",
+                "description": "Get a Beacon response for experimental runs",
                 "operationId": "postRunsRequest",
                 "requestBody": {
                     "content": {
@@ -167,7 +167,7 @@
         },
         "/runs/{id}": {
             "get": {
-                "description": "Get details about one sequencing run, identified by its (unique) 'id'",
+                "description": "Get details about one experimental run, identified by its (unique) 'id'",
                 "operationId": "getOneRun",
                 "responses": {
                     "200": {
@@ -188,7 +188,7 @@
                 }
             ],
             "post": {
-                "description": "Get details about one Run, identified by its (unique) 'id'",
+                "description": "Get details about one experimental run, identified by its (unique) 'id'",
                 "operationId": "postOneRun",
                 "requestBody": {
                     "content": {
@@ -216,7 +216,7 @@
         },
         "/runs/{id}/analyses": {
             "get": {
-                "description": "Get the analysis list from one sequencing run, identified by its (unique) 'id'",
+                "description": "Get a *analyses* response for one experimental run, identified by its (unique) 'id'",
                 "operationId": "getOneRunAnalysis",
                 "parameters": [
                     {
@@ -248,7 +248,7 @@
                 }
             ],
             "post": {
-                "description": "Get the analysis list from one sequencing run, identified by its (unique) 'id'",
+                "description": "Get a *analyses* response for one experimental run, identified by its (unique) 'id'",
                 "operationId": "postOneRunAnalysis",
                 "requestBody": {
                     "content": {
@@ -276,8 +276,8 @@
         },
         "/runs/{id}/g_variants": {
             "get": {
-                "description": "Get the genomic variants list from one run, identified by its (unique) 'id'",
-                "operationId": "getOneRunGenomicVariants",
+                "description": "Get a *genomic variations* response for one experimental run, identified by its (unique) 'id'",
+                "operationId": "getOneRunGenomicVariations",
                 "parameters": [
                     {
                         "$ref": "#/components/parameters/requestedSchema"
@@ -308,8 +308,8 @@
                 }
             ],
             "post": {
-                "description": "Get the genomic variants list from one run, identified by its (unique) 'id'",
-                "operationId": "potOneRunGenomicVariants",
+                "description": "Get a *genomic variations* response for one experimental run, identified by its (unique) 'id'",
+                "operationId": "potOneRunGenomicVariations",
                 "requestBody": {
                     "content": {
                         "application/json": {
diff --git a/models/src/beacon-v2-default-model/analyses/endpoints.yaml b/models/src/beacon-v2-default-model/analyses/endpoints.yaml
index 8f5d5457a..69d8c0249 100644
--- a/models/src/beacon-v2-default-model/analyses/endpoints.yaml
+++ b/models/src/beacon-v2-default-model/analyses/endpoints.yaml
@@ -18,7 +18,7 @@ paths:
         - $ref: '#/components/parameters/limit'
         - $ref: '#/components/parameters/includeResultsetResponses'
         - $ref: '#/components/parameters/filters'
-      description: Get a list of bioinformatics analysis
+      description: Get a Beacon response for bioinformatics analyses
       operationId: getAnalyses
       tags:
         - GET Endpoints
@@ -28,7 +28,7 @@ paths:
         default:
           $ref: https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/framework/json/responses/beaconErrorResponse.json
     post:
-      description: Get a list of bioinformatics analysis
+      description: Get a Beacon response for bioinformatics analyses
       operationId: postAnalysesRequest
       tags:
         - POST Endpoints
@@ -52,7 +52,8 @@ paths:
     parameters:
       - $ref: '#/components/parameters/entryId'
     get:
-      description: Get details about one bioinformatics analysis, identified by its
+      description: >-
+        Get details about one bioinformatics analysis, identified by its
         (unique) 'id'
       operationId: getOneAnalysis
       tags:
@@ -64,7 +65,8 @@ paths:
           description: An unsuccessful operation
           $ref: https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/framework/json/responses/beaconErrorResponse.json
     post:
-      description: Get details about one bioinformatics analysis, identified by its
+      description: >-
+        Get details about one bioinformatics analysis, identified by its
         (unique) 'id'
       operationId: postOneAnalysisRequest
       tags:
@@ -89,9 +91,10 @@ paths:
         - $ref: '#/components/parameters/requestedSchema'
         - $ref: '#/components/parameters/skip'
         - $ref: '#/components/parameters/limit'
-      description: Get the list of variants instances for one bioinformatics analysis,
+      description: >-
+        Get a *genomic variations* response for one bioinformatics analysis,
         identified by its (unique) 'id'
-      operationId: getOneAnalysisVariants
+      operationId: getOneAnalysisVariationsRequest
       tags:
         - GET Endpoints
       responses:
@@ -101,9 +104,10 @@ paths:
           description: An unsuccessful operation
           $ref: https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/framework/json/responses/beaconErrorResponse.json
     post:
-      description: Get the list of variants instances for one bioinformatics analysis,
+      description: >-
+        Get a *genomic variations* response for one bioinformatics analysis,
         identified by its (unique) 'id'
-      operationId: postOneAnalysisVariantsRequest
+      operationId: postOneAnalysisVariationsRequest
       tags:
         - POST Endpoints
       requestBody:
diff --git a/models/src/beacon-v2-default-model/biosamples/endpoints.yaml b/models/src/beacon-v2-default-model/biosamples/endpoints.yaml
index 50b80d8bb..187e8dad7 100644
--- a/models/src/beacon-v2-default-model/biosamples/endpoints.yaml
+++ b/models/src/beacon-v2-default-model/biosamples/endpoints.yaml
@@ -18,7 +18,7 @@ paths:
         - $ref: '#/components/parameters/limit'
         - $ref: '#/components/parameters/includeResultsetResponses'
         - $ref: '#/components/parameters/filters'
-      description: Get a list of biosamples
+      description: Get a Beacon response for biosamples
       operationId: getBiosamples
       tags:
         - GET Endpoints
@@ -28,7 +28,7 @@ paths:
         default:
           $ref: https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/framework/json/responses/beaconErrorResponse.json
     post:
-      description: Get a list of biosamples
+      description: Get a Beacon response for biosamples
       operationId: postBiosamplesRequest
       tags:
         - POST Endpoints
@@ -48,7 +48,8 @@ paths:
     parameters:
       - $ref: '#/components/parameters/entryId'
     get:
-      description: Get details about one biosample, identified by its (unique) 'id'
+      description: >-
+        Get details about one biosample, identified by its (unique) 'id'
       operationId: getOneBiosample
       tags:
         - GET Endpoints
@@ -59,7 +60,8 @@ paths:
           description: An unsuccessful operation
           $ref: https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/framework/json/responses/beaconErrorResponse.json
     post:
-      description: Get details about one Biosample, identified by its (unique) 'id'
+      description: >-
+        Get details about one Biosample, identified by its (unique) 'id'
       operationId: postOneBiosample
       tags:
         - POST Endpoints
@@ -83,9 +85,10 @@ paths:
         - $ref: '#/components/parameters/requestedSchema'
         - $ref: '#/components/parameters/skip'
         - $ref: '#/components/parameters/limit'
-      description: Get the genomic variants list from one biosample, identified by
+      description: >-
+        Get a *genomic variations* response from one biosample, identified by
         its (unique) 'id'
-      operationId: getOneBiosampleGenomicVariants
+      operationId: getOneBiosampleGenomicVariations
       tags:
         - GET Endpoints
       responses:
@@ -95,9 +98,10 @@ paths:
           description: An unsuccessful operation
           $ref: https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/framework/json/responses/beaconErrorResponse.json
     post:
-      description: Get the genomic variants list from one biosample, identified by
+      description: >-
+        Get a *genomic variations* response from one biosample, identified by
         its (unique) 'id'
-      operationId: postOneBiosampleGenomicVariants
+      operationId: postOneBiosampleGenomicVariations
       tags:
         - POST Endpoints
       requestBody:
@@ -120,9 +124,10 @@ paths:
         - $ref: '#/components/parameters/requestedSchema'
         - $ref: '#/components/parameters/skip'
         - $ref: '#/components/parameters/limit'
-      description: Get the analysis list from one biosample, identified by its (unique)
-        'id'
-      operationId: getOneBiosampleAnalysis
+      description: >-
+        Get an *analyses* response from one biosample, identified by its
+        (unique) 'id'
+      operationId: getOneBiosampleAnalyses
       tags:
         - GET Endpoints
       responses:
@@ -132,9 +137,10 @@ paths:
           description: An unsuccessful operation
           $ref: https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/framework/json/responses/beaconErrorResponse.json
     post:
-      description: Get the analysis list from one biosample, identified by its (unique)
-        'id'
-      operationId: postOneBiosampleAnalysis
+      description: >-
+        Get an *analyses* response from one biosample, identified by its
+        (unique) 'id'
+      operationId: postOneBiosampleAnalyses
       tags:
         - POST Endpoints
       requestBody:
@@ -157,8 +163,8 @@ paths:
         - $ref: '#/components/parameters/requestedSchema'
         - $ref: '#/components/parameters/skip'
         - $ref: '#/components/parameters/limit'
-      description: Get the runs list from one biosample, identified by its (unique)
-        'id'
+      description: >-
+        Get a *runs* response from one biosample, identified by its (unique) 'id'
       operationId: getOneBiosampleRuns
       tags:
         - GET Endpoints
@@ -173,8 +179,8 @@ paths:
           description: An unsuccessful operation
           $ref: https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/framework/json/responses/beaconErrorResponse.json
     post:
-      description: Get the runs list from one biosample, identified by its (unique)
-        'id'
+      description: >-
+        Get a *runs* response from one biosample, identified by its (unique) 'id'
       operationId: postOneBiosampleRuns
       tags:
         - POST Endpoints
diff --git a/models/src/beacon-v2-default-model/cohorts/endpoints.yaml b/models/src/beacon-v2-default-model/cohorts/endpoints.yaml
index 9fd0e999a..2b7693669 100644
--- a/models/src/beacon-v2-default-model/cohorts/endpoints.yaml
+++ b/models/src/beacon-v2-default-model/cohorts/endpoints.yaml
@@ -22,7 +22,7 @@ paths:
         - $ref: '#/components/parameters/skip'
         - $ref: '#/components/parameters/limit'
         - $ref: '#/components/parameters/filters'
-      description: Get a list of cohorts
+      description: Get a Beacon *cohorts* response
       operationId: getCohorts
       tags:
         - GET Endpoints
@@ -32,7 +32,7 @@ paths:
         default:
           $ref: https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/framework/json/responses/beaconErrorResponse.json
     post:
-      description: Get a list of cohorts
+      description: Get a Beacon *cohorts* response
       operationId: postCohortsRequest
       tags:
         - POST Endpoints
@@ -89,7 +89,8 @@ paths:
         - $ref: '#/components/parameters/requestedSchema'
         - $ref: '#/components/parameters/skip'
         - $ref: '#/components/parameters/limit'
-      description: Get the individuals from one cohort, identified by its (unique)
+      description: >-
+        Get an *individuals* response for one cohort, identified by its (unique)
         'id'
       operationId: getOneCohortIndividuals
       tags:
@@ -101,7 +102,8 @@ paths:
           description: An unsuccessful operation
           $ref: https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/framework/json/responses/beaconErrorResponse.json
     post:
-      description: Get the individuals from one cohort, identified by its (unique)
+      description: >-
+        Get an *individuals* response for one cohort, identified by its (unique)
         'id'
       operationId: postOneCohortEntries
       tags:
@@ -125,8 +127,9 @@ paths:
       parameters:
         - $ref: '#/components/parameters/skip'
         - $ref: '#/components/parameters/limit'
-      description: Get the list of filtering terms that could be used with a given
-        cohort, identified by its (unique) 'id'
+      description: >-
+        Get a response about the *filtering terms* that could be used with a
+        given cohort, identified by its (unique) 'id'
       operationId: getOneCohortFilteringTerms
       tags:
         - GET Endpoints
@@ -141,8 +144,9 @@ paths:
           description: An unsuccessful operation
           $ref: https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/framework/json/responses/beaconErrorResponse.json
     post:
-      description: Get the list of filtering terms that could be used with a given
-        cohort, identified by its (unique) 'id'
+      description: >-
+        Get a response about the *filtering terms* that could be used with a
+        given cohort, identified by its (unique) 'id'
       operationId: postOneCohortFilteringTerms
       tags:
         - POST Endpoints
diff --git a/models/src/beacon-v2-default-model/datasets/endpoints.yaml b/models/src/beacon-v2-default-model/datasets/endpoints.yaml
index dc2c34d31..b8d70eb68 100644
--- a/models/src/beacon-v2-default-model/datasets/endpoints.yaml
+++ b/models/src/beacon-v2-default-model/datasets/endpoints.yaml
@@ -32,7 +32,7 @@ paths:
         default:
           $ref: https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/framework/json/responses/beaconErrorResponse.json
     post:
-      description: Get a list of datasets
+      description: Get a Beacon *datasets* response
       operationId: postDatasetsRequest
       tags:
         - POST Endpoints
@@ -89,7 +89,8 @@ paths:
         - $ref: '#/components/parameters/requestedSchema'
         - $ref: '#/components/parameters/skip'
         - $ref: '#/components/parameters/limit'
-      description: Get the genomic variants list from one dataset, identified by its
+      description: >-
+        Get a *genomic variations* response for one dataset, identified by its
         (unique) 'id'
       operationId: getOneDatasetEntries
       tags:
@@ -101,7 +102,8 @@ paths:
           description: An unsuccessful operation
           $ref: https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/framework/json/responses/beaconErrorResponse.json
     post:
-      description: Get the genomic variants list from one dataset, identified by its
+      description: >-
+        Get a *genomic variations* response for one dataset, identified by its
         (unique) 'id'
       operationId: postOneDatasetEntries
       tags:
@@ -126,7 +128,8 @@ paths:
         - $ref: '#/components/parameters/requestedSchema'
         - $ref: '#/components/parameters/skip'
         - $ref: '#/components/parameters/limit'
-      description: Get the biosamples list from one dataset, identified by its (unique)
+      description: >-
+        Get a *biosamples* response for one dataset, identified by its (unique)
         'id'
       operationId: getOneDatasetBiosamples
       tags:
@@ -138,7 +141,8 @@ paths:
           description: An unsuccessful operation
           $ref: https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/framework/json/responses/beaconErrorResponse.json
     post:
-      description: Get the biosamples list from one dataset, identified by its (unique)
+      description: >-
+        Get a *biosamples* response for one dataset, identified by its (unique)
         'id'
       operationId: postOneDatasetBiosamples
       tags:
@@ -163,7 +167,8 @@ paths:
         - $ref: '#/components/parameters/requestedSchema'
         - $ref: '#/components/parameters/skip'
         - $ref: '#/components/parameters/limit'
-      description: Get the individuals list from one dataset, identified by its (unique)
+      description: >-
+        Get an *individuals* response for one dataset, identified by its (unique)
         'id'
       operationId: getOneDatasetIndividuals
       tags:
@@ -175,7 +180,8 @@ paths:
           description: An unsuccessful operation
           $ref: https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/framework/json/responses/beaconErrorResponse.json
     post:
-      description: Get the biosamples list from one dataset, identified by its (unique)
+      description: >-
+        Get an *individuals* response for one dataset, identified by its (unique)
         'id'
       operationId: postOneDatasetIndividuals
       tags:
@@ -199,8 +205,9 @@ paths:
       parameters:
         - $ref: '#/components/parameters/skip'
         - $ref: '#/components/parameters/limit'
-      description: Get the list of filtering terms that could be used with a given
-        dataset, identified by its (unique) 'id'
+      description: >-
+        Get a response about the *filtering terms* that could be used with a
+        given dataset, identified by its (unique) 'id'
       operationId: getOneDatasetFilteringTerms
       tags:
         - GET Endpoints
@@ -215,8 +222,9 @@ paths:
           description: An unsuccessful operation
           $ref: https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/framework/json/responses/beaconErrorResponse.json
     post:
-      description: Get the list of filtering terms that could be used with a given
-        dataset, identified by its (unique) 'id'
+      description: >-
+        Get a response about the *filtering terms* that could be used with a
+        given dataset, identified by its (unique) 'id'
       operationId: postOneDatasetFilteringTerms
       tags:
         - POST Endpoints
diff --git a/models/src/beacon-v2-default-model/genomicVariations/endpoints.yaml b/models/src/beacon-v2-default-model/genomicVariations/endpoints.yaml
index 44b59a736..351bccb27 100644
--- a/models/src/beacon-v2-default-model/genomicVariations/endpoints.yaml
+++ b/models/src/beacon-v2-default-model/genomicVariations/endpoints.yaml
@@ -29,8 +29,8 @@ paths:
         - $ref: '#/components/parameters/geneId'
         - $ref: '#/components/parameters/aminoacidChange'
         - $ref: '#/components/parameters/filters'
-      description: Get a list of example entries
-      operationId: getExampleEntries
+      description: Get a Beacon response for genomic variations
+      operationId: getGenomicVariations
       tags:
         - GET Endpoints
       responses:
@@ -39,8 +39,8 @@ paths:
         default:
           $ref: https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/framework/json/responses/beaconErrorResponse.json
     post:
-      description: Get a list of example entries
-      operationId: postExampleEntriesRequest
+      description: Get a Beacon response for genomic variations
+      operationId: postGenomicVariationsRequest
       tags:
         - POST Endpoints
       requestBody:
@@ -59,8 +59,8 @@ paths:
     parameters:
       - $ref: '#/components/parameters/entryId'
     get:
-      description: Get details about one genomic variation, identified by its (unique)
-        'id'
+      description: >-
+        Get details about one genomic variation, identified by its (unique) 'id'
       operationId: getOneGenomicVariation
       tags:
         - GET Endpoints
@@ -71,8 +71,8 @@ paths:
           description: An unsuccessful operation
           $ref: https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/framework/json/responses/beaconErrorResponse.json
     post:
-      description: Get details about one genomic variation, identified by its (unique)
-        'id'
+      description: >-
+        Get details about one genomic variation, identified by its (unique) 'id'
       operationId: postOneGenomicVariation
       tags:
         - POST Endpoints
@@ -96,9 +96,10 @@ paths:
         - $ref: '#/components/parameters/requestedSchema'
         - $ref: '#/components/parameters/skip'
         - $ref: '#/components/parameters/limit'
-      description: Get the biosamples list from one genomic variant, identified by
-        its (unique) 'id'
-      operationId: getOneGenomicVariantBiosamples
+      description: >-
+        Get a *biosamples* response from one genomic variant, identified by its
+        (unique) 'id'
+      operationId: getOneGenomicVariationBiosamples
       tags:
         - GET Endpoints
       responses:
@@ -108,9 +109,10 @@ paths:
           description: An unsuccessful operation
           $ref: https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/framework/json/responses/beaconErrorResponse.json
     post:
-      description: Get the biosamples list from one genomic variant, identified by
-        its (unique) 'id'
-      operationId: postOneGenomicVariantBiosamples
+      description: >-
+        Get a *biosamples* response from one genomic variant, identified by its
+        (unique) 'id'
+      operationId: postOneGenomicVariationBiosamples
       tags:
         - POST Endpoints
       requestBody:
@@ -133,9 +135,10 @@ paths:
         - $ref: '#/components/parameters/requestedSchema'
         - $ref: '#/components/parameters/skip'
         - $ref: '#/components/parameters/limit'
-      description: Get the individuals list from one genomic variant, identified by
+      description: >-
+        Get an *individuals* response from one genomic variant, identified by
         its (unique) 'id'
-      operationId: getOneGenomicVariantIndividuals
+      operationId: getOneGenomicVariationIndividuals
       tags:
         - GET Endpoints
       responses:
@@ -145,9 +148,10 @@ paths:
           description: An unsuccessful operation
           $ref: https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/framework/json/responses/beaconErrorResponse.json
     post:
-      description: Get the biosamples list from one genomic variant, identified by
+      description: >-
+        Get an *individuals* response from one genomic variant, identified by
         its (unique) 'id'
-      operationId: postOneGenomicVariantIndividuals
+      operationId: postOneGenomicVariationIndividuals
       tags:
         - POST Endpoints
       requestBody:
diff --git a/models/src/beacon-v2-default-model/individuals/endpoints.yaml b/models/src/beacon-v2-default-model/individuals/endpoints.yaml
index 7ed5a46fe..156e19851 100644
--- a/models/src/beacon-v2-default-model/individuals/endpoints.yaml
+++ b/models/src/beacon-v2-default-model/individuals/endpoints.yaml
@@ -28,7 +28,7 @@ paths:
         default:
           $ref: https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/framework/json/responses/beaconErrorResponse.json
     post:
-      description: Get a list of example entries
+      description: Get a Beacon response for individuals
       operationId: postIndividualsRequest
       tags:
         - POST Endpoints
@@ -48,7 +48,8 @@ paths:
     parameters:
       - $ref: '#/components/parameters/entryId'
     get:
-      description: Get details about one individual, identified by its (unique) 'id'
+      description: >-
+        Get details about one individual, identified by its (unique) 'id'
       operationId: getOneIndividual
       tags:
         - GET Endpoints
@@ -59,7 +60,8 @@ paths:
           description: An unsuccessful operation
           $ref: https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/framework/json/responses/beaconErrorResponse.json
     post:
-      description: Get details about one Individual, identified by its (unique) 'id'
+      description: >-
+        Get details about one individual, identified by its (unique) 'id'
       operationId: postOneIndividual
       tags:
         - POST Endpoints
@@ -83,7 +85,8 @@ paths:
         - $ref: '#/components/parameters/requestedSchema'
         - $ref: '#/components/parameters/skip'
         - $ref: '#/components/parameters/limit'
-      description: Get the genomic variants list from one individual, identified by
+      description: >-
+        Get a *genomic variations* response for one individual, identified by
         its (unique) 'id'
       operationId: getOneIndividualGenomicVariants
       tags:
@@ -95,7 +98,8 @@ paths:
           description: An unsuccessful operation
           $ref: https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/framework/json/responses/beaconErrorResponse.json
     post:
-      description: Get the genomic variants list from one individual, identified by
+      description: >-
+        Get a *genomic variations* response for one individual, identified by
         its (unique) 'id'
       operationId: potOneIndividualGenomicVariants
       tags:
@@ -120,7 +124,8 @@ paths:
         - $ref: '#/components/parameters/requestedSchema'
         - $ref: '#/components/parameters/skip'
         - $ref: '#/components/parameters/limit'
-      description: Get the biosamples list from one individual, identified by its
+      description: >-
+        Get a *biosamples* response for one individual, identified by its
         (unique) 'id'
       operationId: getOneIndividualBiosamples
       tags:
@@ -132,7 +137,8 @@ paths:
           description: An unsuccessful operation
           $ref: https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/framework/json/responses/beaconErrorResponse.json
     post:
-      description: Get the biosamples list from one individual, identified by its
+      description: >-
+        Get a *biosamples* response for one individual, identified by its
         (unique) 'id'
       operationId: postOneIndividualBiosamples
       tags:
diff --git a/models/src/beacon-v2-default-model/runs/endpoints.yaml b/models/src/beacon-v2-default-model/runs/endpoints.yaml
index 473bea53c..9e3a97442 100644
--- a/models/src/beacon-v2-default-model/runs/endpoints.yaml
+++ b/models/src/beacon-v2-default-model/runs/endpoints.yaml
@@ -18,7 +18,7 @@ paths:
         - $ref: '#/components/parameters/limit'
         - $ref: '#/components/parameters/includeResultsetResponses'
         - $ref: '#/components/parameters/filters'
-      description: Get a list of sequencing runs
+      description: Get a Beacon response for experimental runs
       operationId: getRuns
       tags:
         - GET Endpoints
@@ -28,7 +28,7 @@ paths:
         default:
           $ref: https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/framework/json/responses/beaconErrorResponse.json
     post:
-      description: Get a list of sequencing runs
+      description: Get a Beacon response for experimental runs
       operationId: postRunsRequest
       tags:
         - POST Endpoints
@@ -48,8 +48,8 @@ paths:
     parameters:
       - $ref: '#/components/parameters/entryId'
     get:
-      description: Get details about one sequencing run, identified by its (unique)
-        'id'
+      description: >-
+        Get details about one experimental run, identified by its (unique) 'id'
       operationId: getOneRun
       tags:
         - GET Endpoints
@@ -60,7 +60,8 @@ paths:
           description: An unsuccessful operation
           $ref: https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/framework/json/responses/beaconErrorResponse.json
     post:
-      description: Get details about one Run, identified by its (unique) 'id'
+      description: >-
+        Get details about one experimental run, identified by its (unique) 'id'
       operationId: postOneRun
       tags:
         - POST Endpoints
@@ -84,9 +85,10 @@ paths:
         - $ref: '#/components/parameters/requestedSchema'
         - $ref: '#/components/parameters/skip'
         - $ref: '#/components/parameters/limit'
-      description: Get the genomic variants list from one run, identified by its (unique)
-        'id'
-      operationId: getOneRunGenomicVariants
+      description: >-
+        Get a *genomic variations* response for one experimental run, identified
+        by its (unique) 'id'
+      operationId: getOneRunGenomicVariations
       tags:
         - GET Endpoints
       responses:
@@ -96,9 +98,10 @@ paths:
           description: An unsuccessful operation
           $ref: https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/framework/json/responses/beaconErrorResponse.json
     post:
-      description: Get the genomic variants list from one run, identified by its (unique)
-        'id'
-      operationId: potOneRunGenomicVariants
+      description: >-
+        Get a *genomic variations* response for one experimental run, identified
+        by its (unique) 'id'
+      operationId: potOneRunGenomicVariations
       tags:
         - POST Endpoints
       requestBody:
@@ -121,7 +124,8 @@ paths:
         - $ref: '#/components/parameters/requestedSchema'
         - $ref: '#/components/parameters/skip'
         - $ref: '#/components/parameters/limit'
-      description: Get the analysis list from one sequencing run, identified by its
+      description: >-
+        Get a *analyses* response for one experimental run, identified by its
         (unique) 'id'
       operationId: getOneRunAnalysis
       tags:
@@ -133,7 +137,8 @@ paths:
           description: An unsuccessful operation
           $ref: https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/framework/json/responses/beaconErrorResponse.json
     post:
-      description: Get the analysis list from one sequencing run, identified by its
+      description: >-
+        Get a *analyses* response for one experimental run, identified by its
         (unique) 'id'
       operationId: postOneRunAnalysis
       tags: