Merge branch 'release/drs-1.3.0'

README.md

@@ -1,4 +1,4 @@
-<img src="https://www.ga4gh.org/wp-content/themes/ga4gh-theme/gfx/GA-logo-horizontal-tag-RGB.svg" alt="GA4GH Logo" style="width: 400px;"/>
+/<img src="https://www.ga4gh.org/wp-content/themes/ga4gh-theme/gfx/GA-logo-horizontal-tag-RGB.svg" alt="GA4GH Logo" style="width: 400px;"/>
 
 # Data Repository Service (DRS) API
 
@@ -26,7 +26,7 @@ For more information see our HTML documentation links in the table below.
 |  **Branch** | **Reference Documentation** | Swagger Editor |
 | --- | --- | --- |
 | **develop**: the stable development branch, into which feature branches are merged | [HTML](https://ga4gh.github.io/data-repository-service-schemas/preview/develop/docs/) | [Swagger Editor](https://editor.swagger.io?url=https://ga4gh.github.io/data-repository-service-schemas/preview/develop/openapi.yaml) |
-| **release 1.3.0 (pending)**: The 1.3.0 release of DRS adds the Options endpoint (https://{serverURL}/ga4gh/drs/v1/objects/{object_id}) which allows the caller to get authorization info about a DrsObject. | [HTML](https://ga4gh.github.io/data-repository-service-schemas/preview/release/drs-1.3.0/docs/) | [Swagger Editor](https://editor.swagger.io?url=https://ga4gh.github.io/data-repository-service-schemas/preview/release/drs-1.3.0/openapi.yaml) |
+| **release 1.3.0**: The 1.3.0 release of DRS adds the ability to use the options request method to return the auth issuers for a specific DRS object. | [HTML](https://ga4gh.github.io/data-repository-service-schemas/preview/release/drs-1.3.0/docs/) | [Swagger Editor](https://editor.swagger.io?url=https://ga4gh.github.io/data-repository-service-schemas/preview/release/drs-1.3.0/openapi.yaml) |
 | **release 1.2.0**: The 1.2.0 release of DRS adds the standardized `/service-info` endpoint, and 2 `POST` endpoints that are functionally equivalent to the current `GET` endpoints, but they enable the submission of large passport tokens in the request body. | [HTML](https://ga4gh.github.io/data-repository-service-schemas/preview/release/drs-1.2.0/docs/) | [Swagger Editor](https://editor.swagger.io?url=https://ga4gh.github.io/data-repository-service-schemas/preview/release/drs-1.2.0/openapi.yaml) |
 | **release 1.1.0**: The 1.1.0 release of DRS that includes *no* API changes only documentation changes. This introduces a new URI convention using compact identifiers along with clear directions on how to use identifiers.org/n2t.net to resolve them. | [HTML](https://ga4gh.github.io/data-repository-service-schemas/preview/release/drs-1.1.0/docs/) | [Swagger Editor](https://editor.swagger.io?url=https://ga4gh.github.io/data-repository-service-schemas/preview/release/drs-1.1.0/swagger.yaml) |
 | **release 1.0.0**: The 1.0.0 release of DRS that is now an approved GA4GH standard | [HTML](https://ga4gh.github.io/data-repository-service-schemas/preview/release/drs-1.0.0/docs/) | [Swagger Editor](https://editor.swagger.io?url=https://ga4gh.github.io/data-repository-service-schemas/preview/release/drs-1.0.0/swagger.yaml) |

openapi/components/parameters/Expand.yaml

@@ -10,7 +10,7 @@ description: >-
   included in the result.
 
   If true and the object_id refers to a bundle, then the entire set of objects
-  in the bundle is expanded. That is, if the bundle contains aother bundles,
+  in the bundle is expanded. That is, if the bundle contains other bundles,
   then those other bundles are recursively expanded and included in the result.
   Recursion continues through the entire sub-tree of the bundle.
 

openapi/components/requestBodies/PostObjectBody.yaml

@@ -14,7 +14,7 @@ content:
             included in the result.
 
             If true and the object_id refers to a bundle, then the entire set of objects
-            in the bundle is expanded. That is, if the bundle contains aother bundles,
+            in the bundle is expanded. That is, if the bundle contains other bundles,
             then those other bundles are recursively expanded and included in the result.
             Recursion continues through the entire sub-tree of the bundle.
 

openapi/components/responses/200OkAuthorizations.yaml

@@ -0,0 +1,5 @@
+description: "`Authorizations` were found successfully"
+content:
+  application/json:
+    schema:
+      $ref: '../schemas/Authorizations.yaml'

openapi/components/responses/AuthorizationsNotSupported.yaml

@@ -0,0 +1 @@
+description: "`Authorizations` are not supported for this object. Default to `None`."

openapi/components/schemas/AccessMethod.yaml

@@ -15,10 +15,9 @@ properties:
       - file
     description: Type of the access method.
   access_url:
-    $ref: './AccessURL.yaml'
-    description: >-
-      An `AccessURL` that can be used to fetch the actual object bytes.
-      Note that at least one of `access_url` and `access_id` must be provided.
+    allOf:
+      - $ref: './AccessURL.yaml'
+      - description: An `AccessURL` that can be used to fetch the actual object bytes. Note that at least one of `access_url` and `access_id` must be provided.
   access_id:
     type: string
     description: >-
@@ -29,4 +28,8 @@ properties:
     type: string
     description: >-
       Name of the region in the cloud service provider that the object belongs to.
-    example: us-east-1
+    example: us-east-1
+  authorizations:
+    allOf:
+      - $ref: './Authorizations.yaml'
+      - description: When `access_id` is provided, `authorizations` provides information about how to authorize the `/access` method.

openapi/components/schemas/AccessURL.yaml

@@ -12,4 +12,4 @@ properties:
     description: >-
       An optional list of headers to include in the HTTP request to `url`.
       These headers can be used to provide auth tokens required to fetch the object bytes.
-    example: 'Authorization: Basic Z2E0Z2g6ZHJz'
+    example: 'Authorization: Basic Z2E0Z2g6ZHJz'

openapi/components/schemas/Authorizations.yaml

@@ -0,0 +1,34 @@
+type: object
+properties:
+  supported_types:
+    type: array
+    items:
+      type: string
+      enum:
+        - None
+        - BasicAuth
+        - BearerAuth
+        - PassportAuth
+    description: >-
+      An Optional list of support authorization types. More than one can be supported and tried in sequence.
+      Defaults to `None` if empty or missing.
+  passport_auth_issuers:
+    type: array
+    items:
+      type: string
+    description: >-
+      If authorizations contain `PassportAuth` this is a required list of visa issuers
+      (as found in a visa's `iss` claim) that may authorize access to this object. The caller must
+      only provide passports that contain visas from this list. It is strongly recommended that the caller
+      validate that it is appropriate to send the requested passport/visa to the DRS server to mitigate attacks
+      by malicious DRS servers requesting credentials they should not have.
+  bearer_auth_issuers:
+    type: array
+    items:
+      type: string
+    description: >-
+      If authorizations contain `BearerAuth` this is an optional list of issuers that may authorize access to this object.
+      The caller must provide a token from one of these issuers. If this is empty or missing it assumed the caller knows
+      which token to send via other means. It is strongly recommended that the caller
+      validate that it is appropriate to send the requested token to the DRS server to mitigate attacks
+      by malicious DRS servers requesting credentials they should not have.

openapi/components/schemas/Checksum.yaml

@@ -15,6 +15,6 @@ properties:
       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.
-      Until then, if implementors do choose such an algorithm (e.g. because it's implemented by their storage provider), they SHOULD use an existing
+      Until then, if implementers do choose such an algorithm (e.g. because it's implemented by their storage provider), they SHOULD use an existing
       standard `type` value such as `md5`, `etag`, `crc32c`, `trunc512`, or `sha1`.
-    example: sha-256
+    example: sha-256

openapi/components/schemas/ContentsObject.yaml

@@ -8,8 +8,8 @@ properties:
       A name declared by the bundle author that must be
       used when materialising this object,
       overriding any name directly associated with the object itself.
-      The name must be unique with the containing bundle.
-      This string is made up of uppercase and lowercase letters, decimal digits, hypen, period, and underscore [A-Za-z0-9.-_]. See http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html#tag_03_282[portable filenames].
+      The name must be unique within the containing bundle.
+      This string is made up of uppercase and lowercase letters, decimal digits, hyphen, period, and underscore [A-Za-z0-9.-_]. See http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html#tag_03_282[portable filenames].
   id:
     type: string
     description: >-
@@ -32,4 +32,4 @@ properties:
       "?expand=true" on the request, then this contents array must be present and
       describe the objects within the nested bundle.
     items:
-      $ref: './ContentsObject.yaml'
+      $ref: './ContentsObject.yaml'

openapi/components/schemas/DrsObject.yaml

@@ -13,7 +13,7 @@ properties:
     type: string
     description: |-
       A string that can be used to name a `DrsObject`.
-      This string is made up of uppercase and lowercase letters, decimal digits, hypen, period, and underscore [A-Za-z0-9.-_]. See http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html#tag_03_282[portable filenames].
+      This string is made up of uppercase and lowercase letters, decimal digits, hyphen, period, and underscore [A-Za-z0-9.-_]. See http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html#tag_03_282[portable filenames].
   self_uri:
     type: string
     description: |-

openapi/data_repository_service.openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.0.3
 info:
   title: Data Repository Service
-  version: 1.2.0
+  version: 1.3.0
   x-logo:
     url: 'https://www.ga4gh.org/wp-content/themes/ga4gh-theme/gfx/GA-logo-horizontal-tag-RGB.svg'
   termsOfService: 'https://www.ga4gh.org/terms-and-conditions/'

openapi/paths/objects@{object_id}.yaml

@@ -1,3 +1,29 @@
+options:
+  summary: Get Authorization info about a DrsObject.
+  security:
+    - {}
+  description: >-
+    Returns a list of `Authorizations` that can be used to determine how to authorize requests to `GetObject` or `PostObject`.
+  operationId: OptionsObject
+  parameters:
+    - $ref: '../components/parameters/ObjectId.yaml'
+  responses:
+    200:
+      $ref: '../components/responses/200OkAuthorizations.yaml'
+    204:
+      $ref: '../components/responses/AuthorizationsNotSupported.yaml'
+    400:
+      $ref: '../components/responses/400BadRequest.yaml'
+    404:
+      $ref: '../components/responses/404NotFoundDrsObject.yaml'
+    405:
+      $ref: '../components/responses/AuthorizationsNotSupported.yaml'
+    500:
+      $ref: '../components/responses/500InternalServerError.yaml'
+  tags:
+    - Objects
+  x-swagger-router-controller: ga4gh.drs.server
+
 get:
   summary: Get info about a DrsObject.
   description: >-
@@ -30,13 +56,13 @@ post:
   description: >-
     Returns object metadata, and a list of access methods that can be used to fetch object bytes.
 
-    Method is a POST to accomodate a JWT GA4GH Passport sent in the formData in order to authorize access.
+    Method is a POST to accommodate a JWT GA4GH Passport sent in the formData in order to authorize access.
   operationId: PostObject
   security:
     - PassportAuth: []
   responses:
     200:
-      $ref: '../components/responses/200OkAccess.yaml'
+      $ref: '../components/responses/200OkDrsObject.yaml'
     202:
       $ref: '../components/responses/202Accepted.yaml'
     400:

openapi/paths/objects@{object_id}@access@{access_id}.yaml

@@ -35,7 +35,7 @@ post:
     This method only needs to be called when using an `AccessMethod` that contains an `access_id`
     (e.g., for servers that use signed URLs for fetching object bytes).
 
-    Method is a POST to accomodate a JWT GA4GH Passport sent in the formData in order to authorize access.
+    Method is a POST to accommodate a JWT GA4GH Passport sent in the formData in order to authorize access.
   operationId: PostAccessURL
   security:
     - PassportAuth: []

openapi/tags/Auth.md

@@ -29,23 +29,29 @@ DRS implementers should ensure their solutions restrict access to targets as muc
 
 ## Authentication
 
-### BasicAuth
+### Discovery
+
+The APIs to fetch [DrsObjects](#tag/DrsObjectModel) and [AccessURLs](#tag/AccessURLModel) may require authorization. The authorization mode may vary between DRS objects hosted by a service. The authorization mode may vary between the APIs to fetch a [DrsObject](#tag/DrsObjectModel) and an associated [AccessURL](#tag/AccessURLModel). Implementers should indicate how to authenticate to fetch a [DrsObject](#tag/DrsObjectModel) by implementing the [OptionsOjbect](#operation/OptionsObject) API. Implementers should indicate how to authenticate to fetch an [AccessURL](#tag/AccessURLModel) within a [DrsObject](#tag/DrsObjectModel). 
+
+### Modes
+
+#### BasicAuth
 
 A valid authorization token must be passed in the 'Authorization' header, e.g. "Basic ${token_string}"
 
 | Security Scheme Type | HTTP |
 |----------------------|------|
 | **HTTP Authorization Scheme** | basic |
 
-### BearerAuth
+#### BearerAuth
 
 A valid authorization token must be passed in the 'Authorization' header, e.g. "Bearer ${token_string}"
 
 | Security Scheme Type | HTTP |
 |----------------------|------|
 | **HTTP Authorization Scheme** | bearer |
 
-### PassportAuth
+#### PassportAuth
 
 A valid authorization [GA4GH Passport](https://github.com/ga4gh-duri/ga4gh-duri.github.io/tree/master/researcher_ids) token must be passed in the body of a POST request
 

openapi/tags/CompactIdentifierBasedURIs.md

@@ -8,7 +8,7 @@ See the documentation on the [n2t.net](https://n2t.net/e/compact_ids.html) and [
 
 ## Calling Meta-Resolver APIs for Compact Identifier-Based DRS URIs
 
-Clients resolving Compact Identifier-based URIs need to convert a prefix (e.g. “drs.42”) into an URL pattern. They can do so by calling either the identifiers.org or the n2t.net API, since the two meta-resolvers keep their mapping databases in sync.
+Clients resolving Compact Identifier-based URIs need to convert a prefix (e.g. “drs.42”) into a URL pattern. They can do so by calling either the identifiers.org or the n2t.net API, since the two meta-resolvers keep their mapping databases in sync.
 
 ### Calling the identifiers.org API as a Client
 
@@ -34,7 +34,7 @@ This request returns a JSON structure including various URLs containing an embed
 GET https://registry.api.identifiers.org/restApi/resources/search/findAllByNamespaceId?id=1234
 ```
 
-This request returns a JSON structure including an urlPattern field, whose value is an URL pattern containing a ${id} parameter, such as:
+This request returns a JSON structure including an urlPattern field, whose value is a URL pattern containing a ${id} parameter, such as:
 
 ```
 "urlPattern" : "https://drs.myexample.org/ga4gh/drs/v1/objects/{$id}"
@@ -50,7 +50,7 @@ The client makes a GET request to n2t.net to find information about the namespac
 GET https://n2t.net/drs.42:
 ```
 
-This request returns a text structure including a redirect field, whose value is an URL pattern containing a `$id` parameter, such as:
+This request returns a text structure including a redirect field, whose value is a URL pattern containing an `$id` parameter, such as:
 
 ```
 redirect: https://drs.myexample.org/ga4gh/drs/v1/objects/$id

openapi/tags/DrsApiPrinciples.md

@@ -2,7 +2,7 @@
 
 Each implementation of DRS can choose its own id scheme, as long as it follows these guidelines:
 
-* DRS IDs are strings made up of uppercase and lowercase letters, decimal digits, hypen, period, underscore and tilde [A-Za-z0-9.-_~]. See [RFC 3986 § 2.3](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3).
+* DRS IDs are strings made up of uppercase and lowercase letters, decimal digits, hyphen, period, underscore and tilde [A-Za-z0-9.-_~]. See [RFC 3986 § 2.3](https://datatracker.ietf.org/doc/html/rfc3986#section-2.3).
 * DRS IDs can contain other characters, but they MUST be encoded into valid DRS IDs whenever they are used in API calls. This is because non-encoded IDs may interfere with the interpretation of the objects/{id}/access endpoint. To overcome this limitation use percent-encoding of the ID, see [RFC 3986 § 2.4](https://datatracker.ietf.org/doc/html/rfc3986#section-2.4)
 * One DRS ID MUST always return the same object data (or, in the case of a collection, the same set of objects). This constraint aids with reproducibility.
 * DRS implementations MAY have more than one ID that maps to the same object.
@@ -117,4 +117,4 @@ DRS v1 is a read-only API. We expect that each implementation will define its ow
 ## Standards
 
 The DRS API specification is written in OpenAPI and embodies a RESTful service philosophy. It uses JSON in requests and responses and standard HTTPS on port 443 for information transport.  Optionally, it
-supports authenitcation and authorization using the [GA4GH Passport](https://github.com/ga4gh-duri/ga4gh-duri.github.io/tree/master/researcher_ids) standard.
+supports authentication and authorization using the [GA4GH Passport](https://github.com/ga4gh-duri/ga4gh-duri.github.io/tree/master/researcher_ids) standard.

openapi/tags/ServiceRegistry.md

@@ -5,7 +5,7 @@ The [GA4GH Service Registry API specification](https://github.com/ga4gh-discover
 * Each entry in a Service Registry must have a `url`, indicating the base URL to the web service. For DRS services, the registered `url` must include everything up to
 the standardized `/ga4gh/drs/v1` path. Clients should be able to assume that:
     + Adding `/ga4gh/drs/v1/objects/{object_id}` to the registered `url` will hit the `DrsObject` endpoint
-    + Adding `/ga4gh/drs/v1/service-info` to the the registered `url` will hit the Service Info endpoint
+    + Adding `/ga4gh/drs/v1/service-info` to the registered `url` will hit the Service Info endpoint
 
 Example listing of a DRS API registration from a service registry's `/services` endpoint:
 
@@ -17,7 +17,7 @@ Example listing of a DRS API registration from a service registry's `/services`
         "type": {
             "group": "org.ga4gh",
             "artifact": "drs",
-            "version": "1.2.0"
+            "version": "1.3.0"
         },
         "description": "The Data Repository Service (DRS) API ...",
         "organization": {

pages/more-background-on-compact-identifiers/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.0.3
 info:
   title: More Background on Compact Identifiers
-  version: 1.2.0
+  version: 1.3.0
   x-logo:
     url: 'https://www.ga4gh.org/wp-content/themes/ga4gh-theme/gfx/GA-logo-horizontal-tag-RGB.svg'
   termsOfService: 'https://www.ga4gh.org/terms-and-conditions/'