PRC feedback - strict tool versioning for reproducibility (#93)

* Update to match discussion in DRS
checksum object added and tweaked to match ga4gh/data-repository-service-schemas#282

openapi/ga4gh-tool-discovery.yaml

@@ -103,7 +103,9 @@ paths:
           type: string
           description: >-
             An identifier of the tool version, scoped to this registry, for
-            example `v1`.
+            example `v1`. We recommend that versions use semantic versioning https://semver.org/spec/v2.0.0.html 
+            (For example, `1.0.0` instead of `develop`)
+            
       responses:
         '200':
           description: A tool version.
@@ -459,6 +461,21 @@ paths:
       security:
         - BEARER: []        
 definitions:
+  Checksum:
+    type: object
+    required: ['checksum', 'type']
+    properties:
+      checksum:
+        type: string
+        description: |-
+          The hex-string encoded checksum for the data. 
+      type:
+        type: string
+        description: |-
+          The digest method used to create the checksum.
+          The value (e.g. `sha-256`) SHOULD be listed as `Hash Name String` in the https://github.com/ga4gh-discovery/ga4gh-hash-alg-registry/blob/master/hash-alg.csv[GA4GH Hash Algorithm Registry].
+          Other values MAY be used, as long as implementors are aware of the issues discussed in https://tools.ietf.org/html/rfc6920#section-9.4[RFC6920].
+          GA4GH may provide more explicit guidance for use of non-IANA-registered algorithms in the future.
   ToolFile:
     type: object
     properties:
@@ -587,6 +604,12 @@ definitions:
           An identifier of the version of this tool for this particular tool
           registry.
         example: v1
+      is_production:
+        type: boolean
+        description: >-
+          This version of a tool is guaranteed to not change over time (for example, a 
+          tool built from a tag in git as opposed to a branch). A production quality tool 
+          is required to have a checksum
       images:
         description: >-
           All known docker images (and versions/hashes) used by this tool. If
@@ -654,6 +677,16 @@ definitions:
       updated:
         type: string
         description: Last time the container was updated.
+      checksum:
+        type: array
+        items:
+          $ref: '#/definitions/Checksum'
+        description: >- 
+          A production (immutable) tool version is required to have a hashcode. Not required otherwise, but might be useful to detect changes. 
+          This exposes the hashcode for specific image versions to verify that the container version pulled is actually the version that was indexed by the registry.
+        example: 
+          - checksum: '77af4d6b9913e693e8d0b4b294fa62ade6054e6b2f1ffb617ac955dd63fb0182' 
+            type: sha256
       image_type:
         $ref: '#/definitions/ImageType'
   ImageType:
@@ -695,6 +728,15 @@ definitions:
       content:
         type: string
         description: The content of the file itself. One of url or content is required.
+      checksum:
+        type: array
+        items:
+          $ref: '#/definitions/Checksum'
+        description: >- 
+          A production (immutable) tool version is required to have a hashcode. Not required otherwise, but might be useful to detect changes. 
+        example:
+          - checksum: ea2a5db69bd20a42976838790bc29294df3af02b
+            type: sha1
       url:
         type: string
         description: >-

openapi/openapi.yaml

@@ -108,7 +108,9 @@ paths:
           in: path
           required: true
           description: An identifier of the tool version, scoped to this registry, for
-            example `v1`.
+            example `v1`. We recommend that versions use semantic versioning
+            https://semver.org/spec/v2.0.0.html  (For example, `1.0.0` instead
+            of `develop`)
           schema:
             type: string
       responses:
@@ -582,6 +584,25 @@ components:
       name: Authorization
       in: header
   schemas:
+    Checksum:
+      type: object
+      required:
+        - checksum
+        - type
+      properties:
+        checksum:
+          type: string
+          description: "The hex-string encoded checksum for the data. "
+        type:
+          type: string
+          description: >-
+            The digest method used to create the checksum.
+
+            The value (e.g. `sha-256`) SHOULD be listed as `Hash Name String` in the https://github.com/ga4gh-discovery/ga4gh-hash-alg-registry/blob/master/hash-alg.csv[GA4GH Hash Algorithm Registry].
+
+            Other values MAY be used, as long as implementors are aware of the issues discussed in https://tools.ietf.org/html/rfc6920#section-9.4[RFC6920].
+
+            GA4GH may provide more explicit guidance for use of non-IANA-registered algorithms in the future.
     ToolFile:
       type: object
       properties:
@@ -703,6 +724,11 @@ components:
           description: An identifier of the version of this tool for this particular tool
             registry.
           example: v1
+        is_production:
+          type: boolean
+          description: This version of a tool is guaranteed to not change over time (for
+            example, a  tool built from a tag in git as opposed to a branch). A
+            production quality tool  is required to have a checksum
         images:
           description: All known docker images (and versions/hashes) used by this tool. If
             the tool has to evaluate any of the docker images strings at
@@ -768,6 +794,18 @@ components:
         updated:
           type: string
           description: Last time the container was updated.
+        checksum:
+          type: array
+          items:
+            $ref: "#/components/schemas/Checksum"
+          description: A production (immutable) tool version is required to have a
+            hashcode. Not required otherwise, but might be useful to detect
+            changes.  This exposes the hashcode for specific image versions to
+            verify that the container version pulled is actually the version
+            that was indexed by the registry.
+          example:
+            - checksum: 77af4d6b9913e693e8d0b4b294fa62ade6054e6b2f1ffb617ac955dd63fb0182
+              type: sha256
         image_type:
           $ref: "#/components/schemas/ImageType"
     ImageType:
@@ -807,6 +845,16 @@ components:
         content:
           type: string
           description: The content of the file itself. One of url or content is required.
+        checksum:
+          type: array
+          items:
+            $ref: "#/components/schemas/Checksum"
+          description: "A production (immutable) tool version is required to have a
+            hashcode. Not required otherwise, but might be useful to detect
+            changes. "
+          example:
+            - checksum: ea2a5db69bd20a42976838790bc29294df3af02b
+              type: sha1
         url:
           type: string
           description: Optional url to the underlying content, should include version