Schemas (Input / Output)

Every task specifies a schema for its input, and a schema for its output. These define valid documents to be passed as the input, and what the caller can expect for the output document to look like, respectively.

These schemas are specified using JSON Schema.

Valid JSON Schema Versions

Since JSON Schema specifies several versions (sometimes called "drafts"), we need to be careful which versions are allowed to be used.

In the current implementation, schemas can be written in the JSON Schema versions draft-07 or in 2020-12, with the latter being strongly recommended.

Extension: "Type Sources"

To simplify the tools in the HQS Tasks system, we allow schemas (either root schemas or sub schemas which specify parts of the input/output documents) to have an additional key source which annotates where the type is implemented which corresponds to the schema.

This is particularly used in the Python interface implementation: When writing your tasks in that framework, the schemas for these tasks have a source annotation for each class (Pydantic model, enum type, etc.), which was used in the type annotation of an input or output. This allows the generated client package to simply refer to those types (by generating import statements) instead of requiring to re-generate Python code to implement those. This is in particular helpful if the type was defined outside of the task implementation (e.g., when using a class from an external package).

This additional annotation is still valid in JSON Schema and usually ignored by other tools which process JSON Schema.