Describe versioned TRS URIs (#202)

* Describe versioned TRS URIs

* quick typo fix on way to meeting

* clarify API versioning

Co-authored-by: Denis Yuen <[email protected]>

2.0.0-Data-Model.md

@@ -12,22 +12,84 @@ We are starting with a read-only API due to potentially different views and appr
 
 Multiple formats for descriptors such as [CWL](https://github.com/common-workflow-language/common-workflow-language) and [WDL](https://github.com/broadinstitute/wdl) are permitted. 
 
-#### TRS URIs
-
-For convenience, including potentially when passing content references to a WES server, we define a URI syntax for TRS-accessible content. Strings of the form `trs://<server>/<id>` mean _“you can fetch the content with TRS id `<id>` from the TRS server at `<server>` "_.
-
-For example, if a WES server was asked to process `trs://trs.example.org/123456323`, it would know that it could issue a GET request to `https://trs.example.org/api/ga4gh/trs/v2/tools/123456323` to learn how to fetch that object.
+#### TRS Tool and TRS Tool Version IDs
+
+Each implementation of TRS can choose its own identifier scheme, as long as it
+follows these guidelines:
+
+* TRS Tool and TRS Tool Version 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). TRS Tool and
+  TRS Tool Version IDs MAY further contain percent characters (`%`) whenever
+  they are used in API calls, but only if they were introduced through
+  percent-encoding of any non-valid characters (see next bullet point).
+* TRS Tool and TRS Tool Version IDs can contain other characters, but they MUST
+  be percent-encoded (see [RFC 3986 §
+  2.4](https://datatracker.ietf.org/doc/html/rfc3986#section-2.4)) into valid
+  TRS Tool and TRS Tool Version IDs as per the previous rule whenever they are
+  used in API calls. This is because non-encoded IDs may interfere with the
+  interpretation of routes, e.g., for the `/tools/{id}/versions/{version_id}`
+  endpoint.
+* Any given TRS Tool or TRS Tool Version ID MUST always identify the same
+  resource (tool or tool version, respectively) on a given TRS implementation.
+  This constraint aids with reproducibility.
+* TRS implementations MAY have more than one TRS Tool or TRS Tool Version ID
+  mapping to the same resource (tool or tool version, respectively).
 
-This recommendation is intended to mirror the discussion that went into the [DRS URI scheme](https://ga4gh.github.io/data-repository-service-schemas/preview/develop/docs/#_drs_uris).
+#### TRS URIs
 
-For informational purposes, we recommend that TRS implementations add themselves to https://github.com/ga4gh/tool-registry-service-schemas/blob/develop/registry.json to provide for the possibility of creating a global indexing service and to allow others to more easily discover a TRS implementation. 
+To conveniently pass content references to TRS resources, e.g., to advise a
+[WES](https://github.com/ga4gh/workflow-execution-service-schemas) or
+[TES](https://github.com/ga4gh/task-execution-schemas) service which tool
+(version) to use, we define a URI syntax for TRS-accessible content. Strings of
+the form `trs://<server>/<id>` (unversioned) and
+`trs://<server>/<id>/<version_id>` (versioned) mean _“you can fetch the content
+with TRS Tool ID `<id>` and, if provided, TRS Tool Version ID `<version_id>`
+from the TRS server at `<server>` "_.
+
+For example, if a TRS client was asked to process
+`trs://trs.example.org/tool_ABC/v1.2.3`, it would know that it could, e.g.,
+issue `GET` requests to
+`https://trs.example.org/api/ga4gh/trs/v2/tools/tool_ABC` and
+`https://trs.example.org/api/ga4gh/trs/v2/tools/tool_ABC/versions/v1.2.3` to
+fetch information about tool `tool_ABC` and its version `v1.2.3` from a `v2`
+TRS API hosted at `https://trs.example.org/`, respectively.
+
+> Note that clients issuing requests to TRS services MUST NOT encode forward
+> the special characters slashes separating the `trs`, `<server>`, `<id>` and
+> `<version_id>` components of TRS URIs. However, [TRS Tool IDs and TRS Tool
+> Version IDs](#trs-tool-and-trs-tool-version-ids) containing
+> non-valid characters MUST be encoded _individually_ before constructing TRS
+> URIs. For example, for a TRS Tool ID `tool#1` and a TRS Version ID `(1)`, the
+> correct TRS URI for server `trs.example.org` would be
+> `trs://trs.example.org/tool%231/%281%29`, where `tool%231` and `%281%29` are
+> the percent-encoded TRS Tool and TRS Tool Version IDs, respectively.
+>  
+> Also note that to ensure reproducibility, servers implementing multiple
+> versions of the TRS API specification MUST ensure that, within the limits of
+> schema differences across different API versions, corresponding endpoints
+> return consistent responses.
+
+This recommendation is intended to mirror the discussion that went into the
+[DRS URI
+scheme](https://ga4gh.github.io/data-repository-service-schemas/preview/develop/docs/#_drs_uris),
+with the necessary additions to account for versioned TRS URIs.
 
 ### Misc
 
 The entire schema is shown below, but a more useful form is the Swagger editor to view our [schema in progress](https://editor.swagger.io/?url=https://raw.githubusercontent.com/ga4gh/tool-registry-service-schemas/develop/openapi/ga4gh-tool-discovery.yaml) 
 
 Note that the swagger editor itself can kickstart a project by generating servers and clients in a variety of languages.
 
+#### Central GA4GH Service Registry
+
+For informational purposes, we recommend that TRS implementations add
+themselves to
+<https://github.com/ga4gh/tool-registry-service-schemas/blob/develop/registry.json>
+to provide for the possibility of creating a global indexing service and to
+allow others to more easily discover a TRS implementation.
+
 #### Outstanding Questions
 
 ##### Authentication and Authorization