v2.1 clean up

plantbreeding · Jun 23, 2022 · e1f17e0 · e1f17e0
1 parent 6d333a5
commit e1f17e0
Show file tree

Hide file tree

Showing 72 changed files with 377 additions and 620 deletions.
diff --git a/Specification/BrAPI-Core/Programs/Programs_GET_POST.yaml b/Specification/BrAPI-Core/Programs/Programs_GET_POST.yaml
@@ -8,14 +8,6 @@ paths:
       summary: Get a filtered list of breeding Programs
       description: Get a filtered list of breeding Programs. This list can be filtered by common crop name to narrow results to a specific crop.
       parameters:
-      - $ref: '#/components/parameters/commonCropName'
-      - $ref: '#/components/parameters/programDbId'
-      - name: programName
-        description: Filter by program name. Exact match.
-        in: query
-        required: false
-        schema:
-          type: string
       - name: abbreviation
         description: Filter by program abbreviation. Exact match.
         in: query
@@ -34,6 +26,9 @@ paths:
           enum:
           - STANARD
           - PROJECT
+      - $ref: '#/components/parameters/commonCropName'
+      - $ref: '#/components/parameters/programDbId'
+      - $ref: '#/components/parameters/programName'
       - $ref: '#/components/parameters/externalReferenceID' 
       - $ref: '#/components/parameters/externalReferenceId'
       - $ref: '#/components/parameters/externalReferenceSource'

diff --git a/Specification/BrAPI-Core/Studies/Studies_GET_POST.yaml b/Specification/BrAPI-Core/Studies/Studies_GET_POST.yaml
@@ -29,24 +29,6 @@ paths:
         required: false
         schema:
           type: string
-      - description: Filter by trial
-        in: query
-        name: trialDbId
-        required: false
-        schema:
-          type: string
-      - description: Filter by study DbId
-        in: query
-        name: studyDbId
-        required: false
-        schema:
-          type: string
-      - description: Filter by study name
-        in: query
-        name: studyName
-        required: false
-        schema:
-          type: string
       - description: Filter by study code
         in: query
         name: studyCode
@@ -59,12 +41,6 @@ paths:
         required: false
         schema:
           type: string
-      - description: Filter by germplasm DbId
-        in: query
-        name: germplasmDbId
-        required: false
-        schema:
-          type: string
       - description: Filter by observation variable DbId
         in: query
         name: observationVariableDbId
@@ -106,6 +82,10 @@ paths:
           type: string
       - $ref: '#/components/parameters/commonCropName'
       - $ref: '#/components/parameters/programDbId'
+      - $ref: '#/components/parameters/trialDbId'
+      - $ref: '#/components/parameters/studyDbId'
+      - $ref: '#/components/parameters/studyName'
+      - $ref: '#/components/parameters/germplasmDbId'
       - $ref: '#/components/parameters/externalReferenceID' 
       - $ref: '#/components/parameters/externalReferenceId'
       - $ref: '#/components/parameters/externalReferenceSource'

diff --git a/Specification/BrAPI-Core/Trials/Trials_GET_POST.yaml b/Specification/BrAPI-Core/Trials/Trials_GET_POST.yaml
@@ -62,24 +62,6 @@ paths:
         schema:
           type: string
           format: date
-      - name: studyDbId
-        description: Filter by connected studyDbId
-        in: query
-        required: false
-        schema:
-          type: string
-      - name: trialDbId
-        description: Filter by trialDbId
-        in: query
-        required: false
-        schema:
-          type: string
-      - name: trialName
-        description: Filter by trial name
-        in: query
-        required: false
-        schema:
-          type: string
       - name: trialPUI
         description: Filter by trial PUI
         in: query
@@ -111,8 +93,11 @@ paths:
           - desc
           - DESC
           type: string
-      - $ref: '#/components/parameters/programDbId'
       - $ref: '#/components/parameters/commonCropName'
+      - $ref: '#/components/parameters/programDbId'
+      - $ref: '#/components/parameters/trialDbId'
+      - $ref: '#/components/parameters/trialName'
+      - $ref: '#/components/parameters/studyDbId'
       - $ref: '#/components/parameters/externalReferenceID' 
       - $ref: '#/components/parameters/externalReferenceId'
       - $ref: '#/components/parameters/externalReferenceSource'

diff --git a/Specification/BrAPI-Genotyping/AlleleMatrix/AlleleMatrix_GET.yaml b/Specification/BrAPI-Genotyping/AlleleMatrix/AlleleMatrix_GET.yaml
@@ -7,7 +7,9 @@ paths:
     get:
       summary: Use this endpoint to retrieve a two dimensional matrix of genotype data
       description: |-
-        Use this endpoint to retrieve a two dimensional matrix of genotype data. The response structure is based on the VCF format, with the enhanced ability to slice and merge data sets. This allows the user to return the subset of data they are interested in, without having to download the entire genotype file.
+        Use this endpoint to retrieve a two dimensional matrix of genotype data. The response structure is based on the VCF file format, 
+        but the search and filter parameters give the ability to slice and merge data sets. This allows the user to return the subset of data they are interested in, 
+        without having to download the entire genotype file.
         <br/>Each row of data (outer array) corresponds to a variant definition, and each column (inner array) corresponds to a callSet.    
       parameters:
         - name: dimensionVariantPage

diff --git a/Specification/BrAPI-Genotyping/AlleleMatrix/GroupDescription.md b/Specification/BrAPI-Genotyping/AlleleMatrix/GroupDescription.md
@@ -1 +1,3 @@
 # Group Allele Matrix
+
+The Allele Matrix object is used to describe a matrix of genotyping results. This 2d array of data reduces the overall size of the response for larger datasets, when compared to the Calls endpoints. This makes genotype data retrieval faster and easier. 
diff --git a/Specification/BrAPI-Genotyping/AlleleMatrix/Schemas/AlleleMatrix.yaml b/Specification/BrAPI-Genotyping/AlleleMatrix/Schemas/AlleleMatrix.yaml
@@ -89,11 +89,13 @@ components:
               dataMatrixName:
                 description: |-
                   The name of the field represented in this data matrix. The key word "Genotype" is reserved for the allele matrix. Examples of other metadata matrices include: "Genotype Quality", "Read Depth", and "Haplotype Quality"
+                  <br> This maps to a FORMAT field in the VCF file standard.
                 type: string
                 example: Genotype
               dataMatrixAbbreviation:
                 description: |-
                   The abbreviated code of the field represented in this data matrix. These codes should match the VCF standard when possible and the key word "GT" is reserved for the allele matrix. Examples of other metadata matrices include: "GQ", "RD", and "HQ"
+                  <br> This maps to a FORMAT field in the VCF file standard.
                 type: string
                 example: GT
               dataMatrix:

diff --git a/Specification/BrAPI-Genotyping/AlleleMatrix/Schemas/AlleleMatrixParameters.yaml b/Specification/BrAPI-Genotyping/AlleleMatrix/Schemas/AlleleMatrixParameters.yaml
@@ -16,48 +16,48 @@ components:
       name: preview
       description: |- 
             Default Value = false
-            <br/>
-            If 'preview' is set to true, then the server should only return the lists of 'callSetDbIds', 
-            'variantDbIds', and 'variantSetDbIds'. The server should not return any matrix data. This
-            is intended to be a preview and give the client a sense of how large the matrix returned will be
-            <br/>
-            If 'preview' is set to false or not set (default), then the server should return all the matrix
-            data as requested.
+            <br/>If 'preview' is set to true, then the server should return with the "dataMatrices" field as null or empty. All other data fields should be returned normally. 
+            This is intended to be a preview and give the client a sense of how large the matrix returned will be
+            <br/>If 'preview' is set to false or not set (default), then the server should return all the matrix data as requested.
       in: query
       required: false
       schema:
         type: boolean
     dataMatrixNames:
       name: dataMatrixNames
-      description: dataMatrixNames is a comma seperated list of names (ie 'Genotype, Read Depth' etc). This list controls which data matrices are returned in the response.
+      description: |-
+        "dataMatrixNames" is a comma seperated list of names (ie 'Genotype, Read Depth' etc). This list controls which data matrices are returned in the response.
+        <br> This maps to a FORMAT field in the VCF file standard.
       in: query
       required: false
       schema:
         type: string
     dataMatrixAbbreviations:
       name: dataMatrixAbbreviations
-      description: dataMatrixAbbreviations is a comma seperated list of abbreviations (ie 'GT, RD' etc). This list controls which data matrices are returned in the response.
+      description: |-
+        "dataMatrixAbbreviations" is a comma seperated list of abbreviations (ie 'GT, RD' etc). This list controls which data matrices are returned in the response.
+        <br> This maps to a FORMAT field in the VCF file standard.
       in: query
       required: false
       schema:
         type: string
     callSetDbId:
       name: callSetDbId
-      description: The ID of the `CallSet` to be retrieved.
+      description: The ID which uniquely identifies a `CallSet` within the given database server 
       in: query
       required: false
       schema:
         type: string
     variantDbId:
       name: variantDbId
-      description: The ID of the `Variant` to be retrieved.
+      description: The ID which uniquely identifies a `Variant` within the given database server 
       in: query
       required: false
       schema:
         type: string
     variantSetDbId:
       name: variantSetDbId
-      description: The ID of the `VariantSet` to be retrieved.
+      description: The ID which uniquely identifies a `VariantSet` within the given database server 
       in: query
       required: false
       schema:
@@ -90,35 +90,14 @@ components:
       required: false
       schema:
         type: string
-    germplasmPUI:
-        name: germplasmPUI
-        description: Permanent unique identifier (DOI, URI, etc.)
-        in: query
-        required: false
-        schema:
-          type: string
-    germplasmDbId:
-        name: germplasmDbId
-        description: Internal database identifier
-        in: query
-        required: false
-        schema:
-          type: string
-    germplasmName:
-        name: germplasmName
-        description: Name of the germplasm
-        in: query
-        required: false
-        schema:
-          type: string
     positionRange:
-        name: positionRange
-        description: |-
-          The postion range to search
-          <br/>
-          Uses the format "contig:start-end" where "contig" is the chromosome or contig name, "start" is 
-          the starting position of the range, and "end" is the ending position of the range
-        in: query
-        required: false
-        schema:
-          type: string
+      name: positionRange
+      description: |-
+        The postion range to search
+        <br/> Uses the format "contig:start-end" where "contig" is the chromosome or contig name, "start" is  
+        the starting position of the range, and "end" is the ending position of the range
+        <br> Example: CRHOM_1:12000-14000
+      in: query
+      required: false
+      schema:
+        type: string
diff --git a/Specification/BrAPI-Genotyping/AlleleMatrix/Schemas/AlleleMatrixSearchRequest.yaml b/Specification/BrAPI-Genotyping/AlleleMatrix/Schemas/AlleleMatrixSearchRequest.yaml
@@ -50,13 +50,15 @@ components:
           default: false
           example: true
         dataMatrixNames:
-          description: dataMatrixNames is a list of names (ie 'Genotype', 'Read Depth' etc). This list controls which data matrices are returned in the response.
+          description: |-
+            `dataMatrixNames` is a list of names (ie 'Genotype', 'Read Depth' etc). This list controls which data matrices are returned in the response.
           type: array
           items:
             type: string
           example: ['Genotype', 'Read Depth']
         dataMatrixAbbreviations:
-          description: dataMatrixAbbreviations is a comma seperated list of abbreviations (ie 'GT', 'RD' etc). This list controls which data matrices are returned in the response.
+          description: |-
+            `dataMatrixAbbreviations` is a comma seperated list of abbreviations (ie 'GT', 'RD' etc). This list controls which data matrices are returned in the response.
           type: array
           items:
             type: string
@@ -72,43 +74,43 @@ components:
             type: string
           example: [ '20:1000-35000', '20:87000-125000' ]
         germplasmNames:
-          description: The germplasm to search
+          description: A list of human readable `Germplasm` names
           type: array
           items:
             type: string
           example: [ 'a03202ec', '274e4f63' ]
         germplasmPUIs:
-          description: The germplasm to search
+          description: A list of premenant unique identifiers associated with `Germplasm`
           type: array
           items:
             type: string
           example: [ 'a03202ec', '274e4f63' ]
         germplasmDbIds:
-          description: The germplasm to search
+          description: A list of IDs which uniquely identify `Germplasm` within the given database server 
           type: array
           items:
             type: string
           example: [ 'a03202ec', '274e4f63' ]
         sampleDbIds:
-          description: The samples to search
+          description: A list of IDs which uniquely identify `Samples` within the given database server 
           type: array
           items:
             type: string
           example: [ 'a03202ec', '274e4f63' ]
         callSetDbIds:
-          description: The CallSet to search.
+          description: A list of IDs which uniquely identify `CallSets` within the given database server 
           type: array
           items:
             type: string
           example: [ 'a03202ec', '274e4f63' ]
         variantDbIds: 
-          description: The Variant to search.
+          description: A list of IDs which uniquely identify `Variants` within the given database server 
           type: array
           items:
             type: string
           example: [ 'bba0b258', 'ff97d4f0' ]
         variantSetDbIds: 
-          description: The VariantSet to search.
+          description: A list of IDs which uniquely identify `VariantSets` within the given database server 
           type: array
           items:
             type: string

diff --git a/Specification/BrAPI-Genotyping/AlleleMatrix/Search_AlleleMatrix_POST.yaml b/Specification/BrAPI-Genotyping/AlleleMatrix/Search_AlleleMatrix_POST.yaml
@@ -7,7 +7,7 @@ paths:
     post:
       summary: Submit a search request for a Allele Matrix
       description: |-
-        Use this endpoint to retrieve a two dimensional matrix of genotype data. The response structure is based on the VCF format, with the enhanced ability to slice and merge data sets. This allows the user to return the subset of data they are interested in, without having to download the entire genotype file.
+        Use this endpoint to retrieve a two dimensional matrix of genotype data. The response structure is based on the VCF format, but the search and filter parameters give the ability to slice and merge data sets. This allows the user to return the subset of data they are interested in, without having to download the entire genotype file.
         <br/>Each row of data (outer array) corresponds to a variant definition, and each column (inner array) corresponds to a callSet. 
         <br/>Search requests allow a client to send a complex query for data. However, the server may not respond with the search results immediately. If a server needs more time to process the request, it might respond with a `searchResultsDbId`. Use the corresponding `GET /search/calls/{searchResultsDbId}` to retrieve the results of the search. 
         <br/>Review the <a target="_blank" href="https://wiki.brapi.org/index.php/Search_Services#POST_Search_Entity">Search Services documentation</a> for additional implementation details.

diff --git a/Specification/BrAPI-Genotyping/AlleleMatrix/Search_AlleleMatrix_SearchResultsDbId_GET.yaml b/Specification/BrAPI-Genotyping/AlleleMatrix/Search_AlleleMatrix_SearchResultsDbId_GET.yaml
@@ -7,7 +7,7 @@ paths:
     get:
       summary: Get the results of a Allele Matrix search request
       description: |-
-        Use this endpoint to retrieve a two dimensional matrix of genotype data. The response structure is based on the VCF format, with the enhanced ability to slice and merge data sets. This allows the user to return the subset of data they are interested in, without having to download the entire genotype file.
+        Use this endpoint to retrieve a two dimensional matrix of genotype data. The response structure is based on the VCF format, but the search and filter parameters give the ability to slice and merge data sets. This allows the user to return the subset of data they are interested in, without having to download the entire genotype file.
         <br/>Each row of data (outer array) corresponds to a variant definition, and each column (inner array) corresponds to a callSet. 
         <br/>Clients should submit a search request using the corresponding `POST /search/allelematrix` endpoint. Search requests allow a client to send a complex query for data. However, the server may not respond with the search results immediately. If a server needs more time to process the request, it might respond with a `searchResultsDbId`. Use this endpoint to retrieve the results of the search. 
         <br/>Review the <a target="_blank" href="https://wiki.brapi.org/index.php/Search_Services#POST_Search_Entity">Search Services documentation</a> for additional implementation details.

diff --git a/Specification/BrAPI-Genotyping/CallSets/CallSets_CallSetId_Calls_GET.yaml b/Specification/BrAPI-Genotyping/CallSets/CallSets_CallSetId_Calls_GET.yaml
@@ -10,7 +10,7 @@ paths:
         Gets a list of `Calls` associated with a `CallSet`.
       parameters:
         - name: callSetDbId
-          description: The ID of the `CallSet` to be retrieved.
+          description: The ID which uniquely identifies a `CallSet` within the given database server 
           in: path
           required: true
           schema:

diff --git a/Specification/BrAPI-Genotyping/CallSets/CallSets_CallSetId_GET.yaml b/Specification/BrAPI-Genotyping/CallSets/CallSets_CallSetId_GET.yaml
@@ -9,7 +9,7 @@ paths:
       description: Gets a `CallSet` by ID.
       parameters:
         - name: callSetDbId
-          description: The ID of the `CallSet` to be retrieved.
+          description: The ID which uniquely identifies a `CallSet` within the given database server 
           in: path
           required: true
           schema:
Original file line number	Diff line number	Diff line change
		@@ -1 +1,3 @@
		# Group Allele Matrix

		The Allele Matrix object is used to describe a matrix of genotyping results. This 2d array of data reduces the overall size of the response for larger datasets, when compared to the Calls endpoints. This makes genotype data retrieval faster and easier.