Task specification JSON reference

A CERES task specification is the durable, versioned description of what the demonstrator was asked to do. It defines the run title, ordered tasks and cycle count. Recorder rate, audio, speech, upload, prompt delivery and other capture or export settings are deliberately outside the task specification.

This page documents the version 1 JSON contract enforced by CERES. It is not a separate machine-readable JSON Schema. The CERES task-specification validator remains authoritative for accepted values.

Top-level contract

Version 1 is one JSON object with exactly these fields:

• schema is required and must be the string ceres-task-specification.
• version is required and must be the integer 1.
• runTitle is a required non-empty string.
• runDescription is an optional string. CERES trims it and omits it when it is blank.
• cycleCount is a required positive safe integer.
• tasks is a required, non-empty array in execution order.

Unknown top-level fields are rejected. CERES trims strings, rejects empty required strings and preserves the order of the task array.

Common task fields

Every task has four common fields:

• id is a required non-empty string and must be unique within the specification.
• type is exactly timed, open or pause.
• label is a required non-empty display name.
• instructions is a required non-empty demonstrator cue.

Unknown task fields are rejected. durationS and resetTimeS must be finite, non-negative numbers no greater than Number.MAX_SAFE_INTEGER. repeatCount must be a positive safe integer.

Timed tasks

A timed task requires durationS, repeatCount and resetTimeS. It records until durationS elapses. A zero duration completes immediately.

Open tasks

An open task requires repeatCount and resetTimeS. It must not include durationS. It records until the authoritative Next action completes the attempt.

Pauses

A pause requires durationS. It must not include repeatCount or resetTimeS. It records no task segment and advances when its duration elapses. A zero duration advances immediately.

The JSON contract permits a non-negative resetTimeS. When a specification is applied to a capture configuration, CERES enforces a five-second minimum reset. Use at least 5 when the configured value and captured behaviour must match exactly.

Execution model

CERES executes the tasks array in order. Each timed or open task runs for its repeatCount, with a reset after every attempt, including the final attempt. Pauses occur at their position in the array. Completing the final entry ends one cycle, then CERES repeats the complete ordered array until cycleCount cycles are complete.

Retry creates another attempt for the same task and repetition. The retried segment remains in the durable source journal but is excluded from the final exported sensor rows and video. Pass and Fail annotate a completed attempt without changing its recorded sensor rows or gating advancement.

Complete version 1 example

This valid specification covers timed, open and pause tasks. Its content is checked against the same validator and SHA-256 test vector used by CERES.

{
  "schema": "ceres-task-specification",
  "version": 1,
  "runTitle": "Sample transfer",
  "runDescription": "Move each sample into the rack",
  "cycleCount": 2,
  "tasks": [
    {
      "id": "pick",
      "type": "timed",
      "label": "Pick sample",
      "instructions": "Pick one sample",
      "durationS": 12.5,
      "repeatCount": 3,
      "resetTimeS": 5
    },
    {
      "id": "inspect",
      "type": "open",
      "label": "Inspect sample",
      "instructions": "Inspect until complete",
      "repeatCount": 1,
      "resetTimeS": 5
    },
    {
      "id": "pause",
      "type": "pause",
      "label": "Inter-cycle pause",
      "instructions": "Wait",
      "durationS": 2
    }
  ]
}

Import and preview

Import a task plan from the Samples catalogue, a local JSON file or a public GitHub Gist. A Gist reference may be its URL or bare Gist ID. CERES uses public Gists only and limits each imported file to 1 MB.

The preview shows the parsed specification, its canonical hash and any compatibility warnings before anything changes. Apply merges the run and task fields into the current capture configuration, preserving recorder, audio, speech, upload and export settings. CERES accepts both version 1 task-specification JSON and supported legacy run JSON; the legacy path imports only run and task fields.

Canonical provenance

Before recording, CERES normalises the task specification into canonical JSON and calculates SHA-256 over its UTF-8 bytes. The resulting lowercase hash identifies the exact task plan attached to the episode. A LeRobot shard stores the canonical value at ceres/task-specifications/<hash>.json and references the same version and hash from its episode metadata.

Read Data description and output format for the complete export layout and provenance fields.