JSON schema for the WES data model

LICENSE

@@ -186,7 +186,7 @@ Apache License
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright {yyyy} {name of copyright owner}
+   Copyright 2019 Global Alliance for Genomics and Health
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
@@ -198,4 +198,4 @@ Apache License
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
-   limitations under the License.
+   limitations under the License.

openapi/workflow_execution_service.schema.json

@@ -0,0 +1,277 @@
+{
+  "definitions": {
+    "DefaultWorkflowEngineParameter": {
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "The name of the parameter"
+        },
+        "type": {
+          "type": "string",
+          "description": "Describes the type of the parameter, e.g. float."
+        },
+        "default_value": {
+          "type": "string",
+          "description": "The stringified version of the default parameter. e.g. \"2.45\"."
+        }
+      },
+      "description": "A message that allows one to describe default parameters for a workflow engine."
+    },
+    "Log": {
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "The task or workflow name"
+        },
+        "cmd": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "The command line that was executed"
+        },
+        "start_time": {
+          "type": "string",
+          "description": "When the command started executing, in ISO 8601 format \"%Y-%m-%dT%H:%M:%SZ\""
+        },
+        "end_time": {
+          "type": "string",
+          "description": "When the command stopped executing (completed, failed, or cancelled), in ISO 8601 format \"%Y-%m-%dT%H:%M:%SZ\""
+        },
+        "stdout": {
+          "type": "string",
+          "description": "A URL to retrieve standard output logs of the workflow run or task.  This URL may change between status requests, or may not be available until the task or workflow has finished execution.  Should be available using the same credentials used to access the WES endpoint."
+        },
+        "stderr": {
+          "type": "string",
+          "description": "A URL to retrieve standard error logs of the workflow run or task.  This URL may change between status requests, or may not be available until the task or workflow has finished execution.  Should be available using the same credentials used to access the WES endpoint."
+        },
+        "exit_code": {
+          "type": "integer",
+          "format": "int32",
+          "description": "Exit code of the program"
+        }
+      },
+      "description": "Log and other info"
+    },
+    "ServiceInfo": {
+      "type": "object",
+      "properties": {
+        "workflow_type_versions": {
+          "type": "object",
+          "additionalProperties": {
+            "$ref": "#/definitions/WorkflowTypeVersion"
+          },
+          "description": "A map with keys as the workflow format type name (currently only CWL and WDL are used although a service may support others) and value is a workflow_type_version object which simply contains an array of one or more version strings"
+        },
+        "supported_wes_versions": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "The version(s) of the WES schema supported by this service"
+        },
+        "supported_filesystem_protocols": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "The filesystem protocols supported by this service, currently these may include common protocols using the terms 'http', 'https', 'sftp', 's3', 'gs', 'file', or 'synapse', but others  are possible and the terms beyond these core protocols are currently not fixed.   This section reports those protocols (either common or not) supported by this WES service."
+        },
+        "workflow_engine_versions": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "string"
+          },
+          "description": "The engine(s) used by this WES service, key is engine name (e.g. Cromwell) and value is version"
+        },
+        "default_workflow_engine_parameters": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/DefaultWorkflowEngineParameter"
+          },
+          "description": "Each workflow engine can present additional parameters that can be sent to the workflow engine. This message will list the default values, and their types for each workflow engine."
+        },
+        "system_state_counts": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "integer",
+            "format": "int64"
+          },
+          "description": "The system statistics, key is the statistic, value is the count of runs in that state. See the State enum for the possible keys."
+        },
+        "auth_instructions_url": {
+          "type": "string",
+          "description": "A web page URL with human-readable instructions on how to get an authorization token for use with a specific WES endpoint.          "
+        },
+        "contact_info_url": {
+          "type": "string",
+          "description": "An email address URL (mailto:) or web page URL with contact information for the operator of a specific WES endpoint.  Users of the endpoint should use this to report problems or security vulnerabilities."
+        },
+        "tags": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "string"
+          },
+          "description": "A key-value map of arbitrary, extended metadata outside the scope of the above but useful to report back"
+        }
+      },
+      "description": "A message containing useful information about the running service, including supported versions and default settings."
+    },
+    "State": {
+      "type": "string",
+      "enum": [
+        "UNKNOWN",
+        "QUEUED",
+        "INITIALIZING",
+        "RUNNING",
+        "PAUSED",
+        "COMPLETE",
+        "EXECUTOR_ERROR",
+        "SYSTEM_ERROR",
+        "CANCELED",
+        "CANCELING"
+      ],
+      "default": "UNKNOWN",
+      "description": "- UNKNOWN: The state of the task is unknown. This provides a safe default for messages where this field is missing, for example, so that a missing field does not accidentally imply that the state is QUEUED.\n\n\n - QUEUED: The task is queued.\n\n\n- INITIALIZING: The task has been assigned to a worker and is currently preparing to run. For example, the worker may be turning on, downloading input files, etc.\n\n- RUNNING: The task is running. Input files are downloaded and the first Executor has been started.\n\n- PAUSED: The task is paused. An implementation may have the ability to pause a task, but this is not required.\n\n\n - COMPLETE: The task has completed running. Executors have exited without error\nand output files have been successfully uploaded.\n\n\n - EXECUTOR_ERROR: The task encountered an error in one of the Executor processes. Generally,\nthis means that an Executor exited with a non-zero exit code.\n\n\n - SYSTEM_ERROR: The task was stopped due to a system error, but not from an Executor,\nfor example an upload failed due to network issues, the worker's ran out of disk space, etc.\n\n\n - CANCELED: The task was canceled by the user.\n\n\n  - CANCELING: The task was canceled by the user, and is in the process of stopping.       "
+    },
+    "RunListResponse": {
+      "type": "object",
+      "properties": {
+        "runs": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/RunStatus"
+          },
+          "description": "A list of workflow runs that the service has executed or is executing. The list is filtered to only include runs that the caller has permission to see."
+        },
+        "next_page_token": {
+          "type": "string",
+          "description": "A token which may be supplied as `page_token` in workflow run list request to get the next page of results.  An empty string indicates there are no more items to return."
+        }
+      },
+      "description": "The service will return a RunListResponse when receiving a successful RunListRequest."
+    },
+    "RunLog": {
+      "type": "object",
+      "properties": {
+        "run_id": {
+          "type": "string",
+          "description": "workflow run ID"
+        },
+        "request": {
+          "$ref": "#/definitions/RunRequest",
+          "description": "The original request message used to initiate this execution."
+        },
+        "state": {
+          "$ref": "#/definitions/State",
+          "description": "The state of the run e.g. RUNNING (see State)"
+        },
+        "run_log": {
+          "$ref": "#/definitions/Log",
+          "description": "The logs, and other key info like timing and exit code, for the overall run of this workflow."
+        },
+        "task_logs": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/Log"
+          },
+          "description": "The logs, and other key info like timing and exit code, for each step in the workflow run."
+        },
+        "outputs": {
+          "type": "object",
+          "description": "The outputs from the workflow run."
+        }
+      }
+    },
+    "RunRequest": {
+      "type": "object",
+      "properties": {
+        "workflow_params": {
+          "type": "object",
+          "description": "REQUIRED\nThe workflow run parameterizations (JSON encoded), including input and output file locations"
+        },
+        "workflow_type": {
+          "type": "string",
+          "description": "REQUIRED\nThe workflow descriptor type, must be \"CWL\" or \"WDL\" currently (or another alternative supported by this WES instance)"
+        },
+        "workflow_type_version": {
+          "type": "string",
+          "description": "REQUIRED\nThe workflow descriptor type version, must be one supported by this WES instance"
+        },
+        "tags": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "string"
+          },
+          "description": "OPTIONAL\nA key-value map of arbitrary metadata outside the scope of `workflow_params` but useful to track with this run request"
+        },
+        "workflow_engine_parameters": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "string"
+          },
+          "description": "OPTIONAL\nAdditional parameters can be sent to the workflow engine using this field. Default values for these parameters can be obtained using the ServiceInfo endpoint."
+        },
+        "workflow_url": {
+          "type": "string",
+          "description": "REQUIRED\nThe workflow CWL or WDL document. When `workflow_attachments` is used to attach files, the `workflow_url` may be a relative path to one of the attachments."
+        }
+      },
+      "description": "To execute a workflow, send a run request including all the details needed to begin downloading\nand executing a given workflow."
+    },
+    "RunId": {
+      "type": "object",
+      "properties": {
+        "run_id": {
+          "type": "string",
+          "description": "workflow run ID"
+        }
+      }
+    },
+    "RunStatus": {
+      "type": "object",
+      "required": [
+        "run_id"
+      ],
+      "properties": {
+        "run_id": {
+          "type": "string"
+        },
+        "state": {
+          "$ref": "#/definitions/State"
+        }
+      },
+      "description": "Small description of a workflow run, returned by server during listing"
+    },
+    "WorkflowTypeVersion": {
+      "type": "object",
+      "properties": {
+        "workflow_type_version": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "an array of one or more acceptable types for the `workflow_type`"
+        }
+      },
+      "description": "Available workflow types supported by a given instance of the service."
+    },
+    "ErrorResponse": {
+      "description": "An object that can optionally include information about the error.",
+      "type": "object",
+      "properties": {
+        "msg": {
+          "type": "string",
+          "description": "A detailed error message."
+        },
+        "status_code": {
+          "type": "integer",
+          "description": "The integer representing the HTTP status code (e.g. 200, 404)."
+        }
+      }
+    }
+  }
+}