Types

An item, progress or result schema is an array of field objects. Each object names itself with a taskhoster-name entry and declares a taskhoster-type that fixes how a submitted value is validated and coerced. A field object is { "taskhoster-name": …, "taskhoster-type": …, "taskhoster-required": bool, "taskhoster-max": N }; an enum also carries a taskhoster-values array. An omitted taskhoster-type defaults to text.

The field types

Type	Accepts	Stored as
`text`	Any string. Kept exactly as sent (not trimmed).	string
`email`	A string matching `local@domain.tld` (one `@`, a dotted domain, no whitespace). Trimmed.	string
`url`	A string starting `http://` or `https://` with no whitespace. Trimmed.	string
`integer`	A whole number, optionally signed (e.g. `-12`). Parsed to a number.	number
`number`	Any finite decimal (e.g. `3.14`, `-0.5`). Parsed to a number.	number
`boolean`	A JSON `true`/`false`, or one of `true`/`1`/`yes`/`on` and `false`/`0`/`no`/`off` (case-insensitive).	boolean
`enum`	A string that is exactly one of the declared `taskhoster-values`.	string
`blob`	Base64 text (characters `A–Z a–z 0–9 + /` and up to two trailing `=`). Carries arbitrary binary while keeping the item file plain text.	string (base64)

The spec keys

Key	Applies to	Meaning
`taskhoster-name`	all	The field's name: a non-empty string, unique within the schema. Required on every field object.
`taskhoster-type`	all	One of the types above. Defaults to `text` if omitted.
`taskhoster-required`	all	`true` to reject a submission that omits the field (or sends it empty/null). Defaults to `false`.
`taskhoster-max`	all	Maximum length of the submitted string, checked before coercion. Defaults to `8000`; for a `blob`, `8388608` (8 MiB). A non-positive or non-integer `taskhoster-max` is ignored and the default used.
`taskhoster-values`	`enum`	A non-empty array of the allowed strings. Required for an `enum`; a definition without it is rejected on push.

How validation works

A field that is present but empty ("" or null) counts as absent, so it only errors if it is taskhoster-required.
The taskhoster-max length is checked against the raw string first; over-length values are rejected, not truncated.
The value is then coerced to its type. A value that doesn't match (a bad email, a non-integer, an out-of-set enum, non-base64 for a blob) is an error.
Unknown fields are dropped, not rejected. Only declared fields end up stored.

A failed submission returns every error at once, e.g. { "ok": false, "errors": ["url is required", "format: must be one of: png, jpg"] }.

A blob's taskhoster-max limits the length of the base64 text, not the decoded bytes. Base64 is roughly a third larger than the raw data, so budget the taskhoster-max accordingly.

Examples

"taskhoster-schema-item": [
  { "taskhoster-name": "url",     "taskhoster-type": "url", "taskhoster-required": true },
  { "taskhoster-name": "format",  "taskhoster-type": "enum", "taskhoster-values": ["png", "jpg", "webp"] },
  { "taskhoster-name": "width",   "taskhoster-type": "integer" },
  { "taskhoster-name": "quality", "taskhoster-type": "number" },
  { "taskhoster-name": "sharpen", "taskhoster-type": "boolean" },
  { "taskhoster-name": "note",    "taskhoster-type": "text", "taskhoster-max": 280 },
  { "taskhoster-name": "blob",    "taskhoster-type": "blob", "taskhoster-max": 5000000 }
]