Finding codes¶

Every finding the Rhylthyme validator reports has a code, a message, a where (the step, track or path it is about) and a fix. This page lists every code: what it means, a program that triggers it, and how to fix it. The codes are those of validateProgram in @rhylthyme/timeline/schedule.

Errors make a program invalid; warnings and info notes do not. The Python column says what the rhylthyme package's validator reports for the same program: rhylthyme validate --json (the CLI, which checks the program as written) and validate_program_structured (the library, which expands replicates first). It reports schema problems as one schema_error and has no code of its own for many logic checks.

This page is generated from the catalogue that @rhylthyme/timeline ships (findingCodes, version 2.0.0-beta.7 here) by tools/gen-finding-codes.js; a test fails when it falls behind.

All codes¶

• Schema: not_an_object, not_json, schema_type, schema_enum, schema_const, schema_required, schema_additionalProperties, schema_minItems, schema_maxItems, schema_minLength, schema_maxLength, schema_pattern, schema_minimum, schema_maximum, schema_exclusiveMinimum, schema_exclusiveMaximum, schema_oneOf, schema_anyOf, schema_not, schema_false
• Structure and references: program_id_format, missing_schema_version, empty_track, duplicate_track_id, duplicate_step_id, compound_without_triggers, bad_trigger_logic, bad_trigger, unknown_trigger_type, trigger_without_step_id, dangling_step_ref, self_reference, buffer_without_seconds, bad_trigger_event, offset_without_seconds, choice_ref_no_choice, choice_ref_unknown
• Timing and overlap: missing_duration, unparseable_duration, variable_min_gt_max, variable_without_default, negative_offset_on_fixed, dependency_cycle, track_overlap, tracks_finish_far_apart
• Resources: bad_resource_constraint, duplicate_constraint, bad_max_concurrent, task_not_constrained, unused_constraint
• Instances and replicates: E_INSTANCES_ON_SINGLE, E_EACH_WITH_REPLICATES, E_EACH_COUNT_MISMATCH, E_INFLIGHT_GT_COUNT, E_INFLIGHT_NO_CHAIN, W_UNBARRIERED_CHAIN, I_IMPLICIT_BARRIER, expansion_failed
• Alerts: E_ALERT_BAD_OFFSET, W_ALERT_BEFORE_MANUAL_START, W_ALERT_BEFORE_PROGRAM_START, W_ALERT_BEFORE_INDEFINITE_END
• Instruments: I_INSTRUMENT_DURATION, instrument_bad_shape, instrument_no_end, instrument_unchecked, instrument_unknown_tool_type, instrument_invalid_command, instrument_over_limit, instrument_returns_early, instrument_dose_outlasts_step, instrument_catalog_not_loaded

Base program¶

Each example below is a fragment: its top-level keys replace those of this valid program, which has no findings at all.

{
  "programId": "example",
  "name": "Example",
  "schemaVersion": "0.2.0-alpha",
  "tracks": [
    {
      "trackId": "main",
      "name": "Main",
      "steps": [
        {
          "stepId": "prep",
          "name": "Prep",
          "duration": { "type": "fixed", "seconds": 300 },
          "startTrigger": { "type": "programStart" }
        },
        {
          "stepId": "cook",
          "name": "Cook",
          "duration": { "type": "fixed", "seconds": 600 },
          "startTrigger": { "type": "afterStep", "stepId": "prep" }
        }
      ]
    }
  ],
  "resourceConstraints": []
}

Schema¶

The program does not match the JSON Schema its schemaVersion selects (rhylthyme-spec's, bundled), or cannot be checked against it.

not_an_object¶

Error. The program is not a JSON object.

validateProgram was given an array, a string, a number, null or another non-object. Nothing else is checked: the result has this one error and stats null.

Example. Passed to validateProgram as it is:

["not", "a", "program"]

The whole value passed to validateProgram, not a fragment.

Fix. Pass the full program object ({"programId": ..., "tracks": [...]}), not a string, an array or a wrapper around it.

Python. Python reports nothing for it. Python raises on a program that is not an object instead of reporting a finding.

not_json¶

Error. The program cannot be written as JSON, so the schema was not checked.

A JavaScript caller passed a value JSON cannot carry: a circular reference, a BigInt or similar. The JSON Schema check is skipped and this finding is reported in its place; the logic checks still run. Programs read from JSON text never get it.

Example. Merged over the base program:

{ "metadata": { "bytes": 10 } }

metadata.bytes is passed as a JavaScript BigInt, which no JSON text can carry.

Fix. Pass plain JSON data: no circular references, BigInt values, functions or class instances.

Python. Python reports nothing for it. Python always validates parsed JSON.

schema_type¶

Error. A value has the wrong JSON type.

The schema expects a different type at this path: a string for a name, an integer for maxConcurrent, an object for a duration. Numbers written in quotes ("2") are strings. A value of the wrong type is reported once, not again by the oneOf/anyOf beside it.

Example. Merged over the base program:

{
  "tracks": [
    {
      "trackId": "main",
      "name": "Main",
      "steps": [
        {
          "stepId": "prep",
          "name": 7,
          "duration": { "type": "fixed", "seconds": 300 },
          "startTrigger": { "type": "programStart" }
        }
      ]
    }
  ]
}

Fix. Write the value as the type the message names; for a quoted number, drop the quotes.

Python. Python reports schema_error. Python reports the first schema violation only, as one schema_error whose message is jsonschema's.

schema_enum¶

Error. A value is not one of the allowed choices.

The field accepts a fixed set of strings (an alert's level, a replicates mode, a trigger's event). Choices that tell apart the shapes of a oneOf, such as a duration's type, are reported as schema_oneOf instead.

Example. Merged over the base program:

{
  "tracks": [
    {
      "trackId": "main",
      "name": "Main",
      "steps": [
        {
          "stepId": "prep",
          "name": "Prep",
          "duration": { "type": "fixed", "seconds": 300 },
          "startTrigger": { "type": "programStart" },
          "alerts": [{ "event": "end", "level": "loud" }]
        }
      ]
    }
  ]
}

Fix. Use one of the values listed in the message.

Python. Python reports schema_error. Python reports the first schema violation only, as one schema_error whose message is jsonschema's.

schema_const¶

Error. A value is not the one fixed value the schema allows.

A const keyword pins a field to one value.

Fix. Set the field to the value the message names.

Python. Python reports schema_error. Python reports the first schema violation only, as one schema_error whose message is jsonschema's.

schema_required¶

Error. A required property is missing.

Every program needs programId, name, tracks and resourceConstraints (or environment / environmentType); every track a trackId, name and steps; every step a stepId, name and startTrigger; every resource constraint a task and maxConcurrent. A missing startTrigger's fix names the step to chain after.

Example. Merged over the base program:

{
  "tracks": [
    {
      "trackId": "main",
      "steps": [
        {
          "stepId": "prep",
          "name": "Prep",
          "duration": { "type": "fixed", "seconds": 300 },
          "startTrigger": { "type": "programStart" }
        }
      ]
    }
  ]
}

Fix. Add the property the message names.

Python. Python reports schema_error. Python reports the first schema violation only, as one schema_error whose message is jsonschema's.

schema_additionalProperties¶

Error. An object has a property the schema does not allow.

Some objects are closed (instrument, instrument actions, alerts, ...): any key besides the listed ones is an error, usually a typo. Programs, tracks, steps and triggers are open and accept extra keys.

Example. Merged over the base program:

{
  "tracks": [
    {
      "trackId": "main",
      "name": "Main",
      "steps": [
        {
          "stepId": "prep",
          "name": "Prep",
          "duration": { "type": "fixed", "seconds": 300 },
          "startTrigger": { "type": "programStart" },
          "instrument": {
            "tool": "shaker",
            "toolType": "bioshake",
            "command": "start_shake",
            "params": { "speed": 1000, "duration": 300 },
            "retries": 2
          }
        }
      ]
    }
  ]
}

Fix. Remove the key or fix its spelling; the fix lists the keys allowed there.

Python. Python reports schema_error. Python reports the first schema violation only, as one schema_error whose message is jsonschema's.

schema_minItems¶

Error. A list has too few items.

Lists such as a compound trigger's triggers (at least 2), an instrument's start/end actions and a step's alerts must not be empty or too short.

Example. Merged over the base program:

{
  "tracks": [
    {
      "trackId": "main",
      "name": "Main",
      "steps": [
        {
          "stepId": "prep",
          "name": "Prep",
          "duration": { "type": "fixed", "seconds": 300 },
          "startTrigger": { "type": "programStart" },
          "alerts": []
        }
      ]
    }
  ]
}

Fix. Add items, or remove the optional list entirely.

Python. Python reports schema_error. Python reports the first schema violation only, as one schema_error whose message is jsonschema's.

schema_maxItems¶

Error. A list has too many items.

A maxItems keyword caps a list's length.

Fix. Shorten the list.

Python. Python reports schema_error. Python reports the first schema violation only, as one schema_error whose message is jsonschema's.

schema_minLength¶

Error. A string is shorter than allowed (usually empty).

Names that must not be empty: an instrument's tool and command, an alert's message.

Example. Merged over the base program:

{
  "tracks": [
    {
      "trackId": "main",
      "name": "Main",
      "steps": [
        {
          "stepId": "prep",
          "name": "Prep",
          "duration": { "type": "fixed", "seconds": 300 },
          "startTrigger": { "type": "programStart" },
          "instrument": { "tool": "", "command": "start_shake" }
        }
      ]
    }
  ]
}

Fix. Give the string a value, or remove the optional field.

Python. Python reports schema_error. Python reports the first schema violation only, as one schema_error whose message is jsonschema's.

schema_maxLength¶

Error. A string is longer than allowed.

An alert's message is at most 200 characters (code points, as Python counts them).

Example. Merged over the base program:

{
  "tracks": [
    {
      "trackId": "main",
      "name": "Main",
      "steps": [
        {
          "stepId": "prep",
          "name": "Prep",
          "duration": { "type": "fixed", "seconds": 300 },
          "startTrigger": { "type": "programStart" },
          "alerts": [
            {
              "event": "end",
              "message": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
            }
          ]
        }
      ]
    }
  ]
}

Fix. Shorten the string to the length the message names.

Python. Python reports schema_error. Python reports the first schema violation only, as one schema_error whose message is jsonschema's.

schema_pattern¶

Error. A string does not match the required pattern.

Schema 0.3.0-alpha constrains a few identifiers: metadata.varianceFactors keys (a letter, then letters, digits, _ and -) and a duration's calibratedFrom.programVersion ("sha256:" and 64 hex digits; inside a duration it is reported as schema_oneOf).

Example. Merged over the base program:

{
  "schemaVersion": "0.3.0-alpha",
  "metadata": { "varianceFactors": [{ "key": "2nd oven", "type": "number" }] }
}

Fix. Make the string match the pattern in the message.

Python. Python reports schema_error. Python reports the first schema violation only, as one schema_error whose message is jsonschema's.

schema_minimum¶

Error. A number is below the minimum.

maxConcurrent is at least 1; durations and their bounds are at least 0.

Example. Merged over the base program:

{ "resourceConstraints": [{ "task": "oven", "maxConcurrent": 0 }] }

Fix. Use a value at or above the minimum the message names.

Python. Python reports schema_error. Python reports the first schema violation only, as one schema_error whose message is jsonschema's.

schema_maximum¶

Error. A number is above the maximum.

A taskResources fraction (the share of a resource a step occupies) is at most 1.

Example. Merged over the base program:

{
  "tracks": [
    {
      "trackId": "main",
      "name": "Main",
      "steps": [
        {
          "stepId": "prep",
          "name": "Prep",
          "duration": { "type": "fixed", "seconds": 300 },
          "startTrigger": { "type": "programStart" },
          "taskResources": [{ "name": "oven", "fraction": 1.5 }]
        }
      ]
    }
  ]
}

Also emits task_not_constrained for the oven.

Fix. Use a value at or below the maximum the message names.

Python. Python reports schema_error. Python reports the first schema violation only, as one schema_error whose message is jsonschema's.

schema_exclusiveMinimum¶

Error. A number must be greater than a bound and is not.

An instrument's or action's timeoutSeconds must be greater than 0.

Example. Merged over the base program:

{
  "tracks": [
    {
      "trackId": "main",
      "name": "Main",
      "steps": [
        {
          "stepId": "prep",
          "name": "Prep",
          "duration": { "type": "fixed", "seconds": 300 },
          "startTrigger": { "type": "programStart" },
          "instrument": {
            "tool": "shaker",
            "toolType": "bioshake",
            "command": "start_shake",
            "params": { "speed": 1000, "duration": 300 },
            "timeoutSeconds": 0
          }
        }
      ]
    }
  ]
}

Fix. Use a value greater than the bound, or remove the optional field.

Python. Python reports schema_error. Python reports the first schema violation only, as one schema_error whose message is jsonschema's.

schema_exclusiveMaximum¶

Error. A number must be less than a bound and is not.

An exclusiveMaximum keyword caps a number below a bound.

Fix. Use a value below the bound.

Python. Python reports schema_error. Python reports the first schema violation only, as one schema_error whose message is jsonschema's.

schema_oneOf¶

Error. A value matches none, or more than one, of the allowed shapes.

Durations, start triggers and the program's own startTrigger have several shapes told apart by their type. A value that fits none gets the closest shape's first problem (or the list of allowed types); a value that fits two (a duration with both seconds and timeString) is ambiguous.

Example. Merged over the base program:

{
  "tracks": [
    {
      "trackId": "main",
      "name": "Main",
      "steps": [
        {
          "stepId": "prep",
          "name": "Prep",
          "duration": { "type": "fixd", "seconds": 300 },
          "startTrigger": { "type": "programStart" }
        }
      ]
    }
  ]
}

Fix. Follow the fix: set type to an allowed value, add the keys the closest shape needs, or remove the keys that make it ambiguous.

Python. Python reports schema_error. Python reports the first schema violation only, as one schema_error whose message is jsonschema's.

schema_anyOf¶

Error. A value matches none of the alternatives it may take.

A program needs resourceConstraints, environment or environmentType; an instrument needs a command, an until, or start/end actions. The message lists the alternatives.

Example. Merged over the base program, without resourceConstraints:

{}

Fix. Add one of the alternatives the message lists.

Python. Python reports schema_error. Python reports the first schema violation only, as one schema_error whose message is jsonschema's.

schema_not¶

Error. A value has a combination of keys the schema forbids.

An instrument has both command and until (only one call can end the step); a program has resourceConstraints together with environment or environmentType.

Example. Merged over the base program:

{
  "tracks": [
    {
      "trackId": "main",
      "name": "Main",
      "steps": [
        {
          "stepId": "prep",
          "name": "Prep",
          "duration": { "type": "fixed", "seconds": 300 },
          "startTrigger": { "type": "programStart" },
          "instrument": {
            "tool": "shaker",
            "command": "start_shake",
            "until": { "command": "wait" }
          }
        }
      ]
    }
  ]
}

Also emits instrument_bad_shape.

Fix. Keep only one of the keys the message names.

Python. Python reports schema_error. Python reports the first schema violation only, as one schema_error whose message is jsonschema's.

schema_false¶

Error. A value is present where the schema allows nothing.

A false subschema forbids any value at that path.

Fix. Remove the value.

Python. Python reports schema_error. Python reports the first schema violation only, as one schema_error whose message is jsonschema's.

Structure and references¶

Ids, triggers and the references between steps.

program_id_format¶

Warning. programId is not kebab-case.

programId should start with a letter or digit and contain only letters, digits, dashes and underscores, so it is safe in URLs and file names.

Example. Merged over the base program:

{ "programId": "My Program!" }

Fix. Use lowercase letters, digits and dashes, e.g. "my-program".

Python. Python reports nothing for it.

missing_schema_version¶

Warning. schemaVersion is missing.

Without schemaVersion the program is checked against the 0.2.0-alpha schema and the viewer assumes 0.1.0. instances triggers and maxInFlight need 0.3.0-alpha.

Example. Merged over the base program, without schemaVersion:

{}

Fix. Set schemaVersion: "0.1.0", "0.2.0-alpha" (choice branching) or "0.3.0-alpha" (instances on triggers).

Python. Python reports nothing for it.

empty_track¶

Warning. A track has no steps; it is left out.

A track whose steps list is missing or empty (and that names no templateId) is dropped before the other checks, as Python's expander drops it.

Example. Merged over the base program:

{
  "tracks": [
    {
      "trackId": "main",
      "name": "Main",
      "steps": [
        {
          "stepId": "prep",
          "name": "Prep",
          "duration": { "type": "fixed", "seconds": 300 },
          "startTrigger": { "type": "programStart" }
        }
      ]
    },
    { "trackId": "idle", "name": "Idle", "steps": [] }
  ]
}

Fix. Add steps to the track or remove it.

Python. rhylthyme validate reports schema_error, as an error; validate_program_structured reports nothing. rhylthyme validate checks the program as written, where an empty steps list breaks the schema; validate_program_structured drops the track while expanding, as JS does, and says nothing.

duplicate_track_id¶

Error. Two tracks share a trackId.

trackIds must be unique: the renderer, the runner and replicate expansion address tracks by id.

Example. Merged over the base program:

{
  "tracks": [
    {
      "trackId": "main",
      "name": "Main",
      "steps": [
        {
          "stepId": "prep",
          "name": "Prep",
          "duration": { "type": "fixed", "seconds": 300 },
          "startTrigger": { "type": "programStart" }
        }
      ]
    },
    {
      "trackId": "main",
      "name": "Main",
      "steps": [
        {
          "stepId": "cook",
          "name": "Cook",
          "duration": { "type": "fixed", "seconds": 300 },
          "startTrigger": { "type": "programStart" }
        }
      ]
    }
  ]
}

Fix. Give every track its own trackId.

Python. Python reports nothing for it.

duplicate_step_id¶

Error. A stepId is used more than once.

stepIds must be unique across the whole program, not only within a track, since triggers refer to steps by id alone. Replicate copies get ids "-r"; a hand-written step with such an id collides with them.

Example. Merged over the base program:

{
  "tracks": [
    {
      "trackId": "main",
      "name": "Main",
      "steps": [
        {
          "stepId": "prep",
          "name": "Prep",
          "duration": { "type": "fixed", "seconds": 300 },
          "startTrigger": { "type": "programStart" }
        }
      ]
    },
    {
      "trackId": "side",
      "name": "Side",
      "steps": [
        {
          "stepId": "prep",
          "name": "Prep",
          "duration": { "type": "fixed", "seconds": 300 },
          "startTrigger": { "type": "programStart" }
        }
      ]
    }
  ]
}

Fix. Rename one of the steps and update the triggers that point at it.

Python. Python reports duplicate_step_id.

compound_without_triggers¶

Error. A trigger has logic but no triggers list.

logic ("all"/"any") combines the triggers in triggers; on a single trigger it has nothing to combine. The schema accepts the extra key on a single trigger, so this check names it.

Example. Merged over the base program:

{
  "tracks": [
    {
      "trackId": "main",
      "name": "Main",
      "steps": [
        {
          "stepId": "prep",
          "name": "Prep",
          "duration": { "type": "fixed", "seconds": 300 },
          "startTrigger": { "type": "programStart", "logic": "all" }
        }
      ]
    }
  ]
}

Fix. Remove logic, or make the trigger compound: {"logic": "all", "triggers": [...]} with at least two triggers.

Python. Python reports nothing for it.

bad_trigger_logic¶

Error. A trigger's logic is not "all" or "any".

Reported when the trigger otherwise passes the schema as a single trigger that also carries logic and triggers keys; a compound trigger with a bad logic value is a schema_oneOf finding.

Example. Merged over the base program:

{
  "tracks": [
    {
      "trackId": "main",
      "name": "Main",
      "steps": [
        {
          "stepId": "prep",
          "name": "Prep",
          "duration": { "type": "fixed", "seconds": 300 },
          "startTrigger": { "type": "programStart" }
        }
      ]
    },
    {
      "trackId": "side",
      "name": "Side",
      "steps": [
        {
          "stepId": "cook",
          "name": "Cook",
          "duration": { "type": "fixed", "seconds": 300 },
          "startTrigger": {
            "type": "programStart",
            "logic": "xor",
            "triggers": [
              { "type": "afterStep", "stepId": "prep" },
              { "type": "programStart" }
            ]
          }
        }
      ]
    }
  ]
}

Fix. Use logic "all" (every trigger must fire) or "any" (the first one starts the step).

Python. Python reports nothing for it.

bad_trigger¶

Error. A trigger inside a compound trigger is not an object.

Meant for a non-object entry in a compound trigger's triggers list.

Fix. Make every entry of triggers an object such as {"type": "afterStep", "stepId": "..."}.

Python. Python reports nothing for it.

unknown_trigger_type¶

Error. A trigger's type is not one the runner knows.

Known types: programStart, programStartOffset, afterStep, afterStepWithBuffer, manual, onAbort. A bad type on a trigger the schema checks is a schema_oneOf finding; this check reaches the entries of a triggers list on a trigger the schema took as a single trigger.

Example. Merged over the base program:

{
  "tracks": [
    {
      "trackId": "main",
      "name": "Main",
      "steps": [
        {
          "stepId": "prep",
          "name": "Prep",
          "duration": { "type": "fixed", "seconds": 300 },
          "startTrigger": { "type": "programStart" }
        }
      ]
    },
    {
      "trackId": "side",
      "name": "Side",
      "steps": [
        {
          "stepId": "cook",
          "name": "Cook",
          "duration": { "type": "fixed", "seconds": 300 },
          "startTrigger": {
            "type": "programStart",
            "logic": "all",
            "triggers": [
              { "type": "afterStepp", "stepId": "prep" },
              { "type": "programStart" }
            ]
          }
        }
      ]
    }
  ]
}

Fix. Use programStart, programStartOffset, afterStep, afterStepWithBuffer, manual or onAbort.

Python. Python reports nothing for it.

trigger_without_step_id¶

Error. An afterStep, afterStepWithBuffer or onAbort trigger has an empty stepId.

These triggers wait for another step and need its id. The schema requires the key; this check catches an empty string.

Example. Merged over the base program:

{
  "tracks": [
    {
      "trackId": "main",
      "name": "Main",
      "steps": [
        {
          "stepId": "prep",
          "name": "Prep",
          "duration": { "type": "fixed", "seconds": 300 },
          "startTrigger": { "type": "programStart" }
        }
      ]
    },
    {
      "trackId": "side",
      "name": "Side",
      "steps": [
        {
          "stepId": "cook",
          "name": "Cook",
          "duration": { "type": "fixed", "seconds": 300 },
          "startTrigger": { "type": "afterStep", "stepId": "" }
        }
      ]
    }
  ]
}

Fix. Set stepId to the step this one waits for.

Python. Python reports dangling_step_ref. Python reports the empty id as a reference to a step that does not exist.

dangling_step_ref¶

Error. A trigger waits for a step that does not exist.

The stepId in an afterStep, afterStepWithBuffer or onAbort trigger matches no step. Ids are case-sensitive; after replicate expansion a replicated step's copies are "-r1", "-r2", ... and the authored id is kept for barriers.

Example. Merged over the base program:

{
  "tracks": [
    {
      "trackId": "main",
      "name": "Main",
      "steps": [
        {
          "stepId": "prep",
          "name": "Prep",
          "duration": { "type": "fixed", "seconds": 300 },
          "startTrigger": { "type": "programStart" }
        },
        {
          "stepId": "cook",
          "name": "Cook",
          "duration": { "type": "fixed", "seconds": 300 },
          "startTrigger": { "type": "afterStep", "stepId": "Prep" }
        }
      ]
    }
  ]
}

Fix. Point the trigger at an existing stepId (check case and spelling).

Python. Python reports dangling_step_ref.

self_reference¶

Error. A step waits for itself.

A step's trigger names its own stepId, so it can never start.

Example. Merged over the base program:

{
  "tracks": [
    {
      "trackId": "main",
      "name": "Main",
      "steps": [
        {
          "stepId": "prep",
          "name": "Prep",
          "duration": { "type": "fixed", "seconds": 300 },
          "startTrigger": { "type": "afterStep", "stepId": "prep" }
        }
      ]
    }
  ]
}

Also emits dependency_cycle.

Fix. Point the trigger at the step before it, or use programStart.

Python. Python reports nothing for it. Python reports nothing; the step is left unscheduled.

buffer_without_seconds¶

Error. An afterStepWithBuffer trigger has no bufferSeconds.

The schema requires bufferSeconds on a trigger it checks; this check reaches the entries of a triggers list on a trigger the schema took as a single trigger.

Example. Merged over the base program:

{
  "tracks": [
    {
      "trackId": "main",
      "name": "Main",
      "steps": [
        {
          "stepId": "prep",
          "name": "Prep",
          "duration": { "type": "fixed", "seconds": 300 },
          "startTrigger": { "type": "programStart" }
        }
      ]
    },
    {
      "trackId": "side",
      "name": "Side",
      "steps": [
        {
          "stepId": "cook",
          "name": "Cook",
          "duration": { "type": "fixed", "seconds": 300 },
          "startTrigger": {
            "type": "programStart",
            "logic": "all",
            "triggers": [
              { "type": "afterStepWithBuffer", "stepId": "prep" },
              { "type": "programStart" }
            ]
          }
        }
      ]
    }
  ]
}

Fix. Add bufferSeconds (seconds or a time string such as "5m"), or use afterStep.

Python. Python reports nothing for it.

bad_trigger_event¶

Error. A trigger's event is not "start" or "end".

event chooses whether the trigger anchors on the referenced step's start or end (the default). A bad value on a trigger the schema checks is a schema finding; this check reaches the entries of a triggers list on a trigger the schema took as a single trigger.

Example. Merged over the base program:

{
  "tracks": [
    {
      "trackId": "main",
      "name": "Main",
      "steps": [
        {
          "stepId": "prep",
          "name": "Prep",
          "duration": { "type": "fixed", "seconds": 300 },
          "startTrigger": { "type": "programStart" }
        }
      ]
    },
    {
      "trackId": "side",
      "name": "Side",
      "steps": [
        {
          "stepId": "cook",
          "name": "Cook",
          "duration": { "type": "fixed", "seconds": 300 },
          "startTrigger": {
            "type": "programStart",
            "logic": "all",
            "triggers": [
              { "type": "afterStep", "stepId": "prep", "event": "middle" },
              { "type": "programStart" }
            ]
          }
        }
      ]
    }
  ]
}

Fix. Use event "start" or "end", or leave it out ("end").

Python. Python reports nothing for it.

offset_without_seconds¶

Error. A programStartOffset trigger has no offsetSeconds.

The schema requires offsetSeconds on a trigger it checks; this check reaches the entries of a triggers list on a trigger the schema took as a single trigger.

Example. Merged over the base program:

{
  "tracks": [
    {
      "trackId": "main",
      "name": "Main",
      "steps": [
        {
          "stepId": "prep",
          "name": "Prep",
          "duration": { "type": "fixed", "seconds": 300 },
          "startTrigger": {
            "type": "programStart",
            "logic": "all",
            "triggers": [{ "type": "programStartOffset" }, { "type": "programStart" }]
          }
        }
      ]
    }
  ]
}

Fix. Add offsetSeconds (seconds or a time string such as "10m"), or use programStart.

Python. Python reports nothing for it.

choice_ref_no_choice¶

Error. A trigger's choiceId refers to a step that offers no choice.

choiceId makes a step run only when the referenced step's choice selects that option (schema 0.2.0-alpha branching). The referenced step has no choice.

Example. Merged over the base program:

{
  "tracks": [
    {
      "trackId": "main",
      "name": "Main",
      "steps": [
        {
          "stepId": "prep",
          "name": "Prep",
          "duration": { "type": "fixed", "seconds": 300 },
          "startTrigger": { "type": "programStart" }
        },
        {
          "stepId": "cook",
          "name": "Cook",
          "duration": { "type": "fixed", "seconds": 300 },
          "startTrigger": { "type": "afterStep", "stepId": "prep", "choiceId": "red" }
        }
      ]
    }
  ]
}

Fix. Add a choice with that option to the referenced step, or remove choiceId.

Python. Python reports choice_ref. Python has one code for both choiceId problems.

choice_ref_unknown¶

Error. A trigger's choiceId is not one of the referenced step's options.

The referenced step offers a choice, but none of its options has this choiceId. The message lists the options.

Example. Merged over the base program:

{
  "tracks": [
    {
      "trackId": "main",
      "name": "Main",
      "steps": [
        {
          "stepId": "pick",
          "name": "Pick",
          "duration": { "type": "fixed", "seconds": 60 },
          "startTrigger": { "type": "programStart" },
          "choice": {
            "prompt": "Sauce?",
            "options": [
              { "choiceId": "red", "label": "Red" },
              { "choiceId": "white", "label": "White" }
            ]
          }
        },
        {
          "stepId": "cook",
          "name": "Cook",
          "duration": { "type": "fixed", "seconds": 300 },
          "startTrigger": { "type": "afterStep", "stepId": "pick", "choiceId": "pesto" }
        }
      ]
    }
  ]
}

Fix. Use one of the option ids the message lists (ids are case-sensitive).

Python. Python reports choice_ref. Python has one code for both choiceId problems.

Timing and overlap¶

Durations, the resolved timeline, cycles and steps that overlap in a track.

missing_duration¶

Error. A step has no duration.

Every step needs a duration, except an instrument step whose command or until call ends it (see I_INSTRUMENT_DURATION) or one with only start/end actions (see instrument_no_end).

Example. Merged over the base program:

{
  "tracks": [
    {
      "trackId": "main",
      "name": "Main",
      "steps": [
        { "stepId": "prep", "name": "Prep", "startTrigger": { "type": "programStart" } }
      ]
    }
  ]
}

Fix. Add duration: {"type": "fixed", "seconds": 300} (or "5m"), variable with min/max, or indefinite.

Python. Python reports nothing for it. Python times a step with no duration as 0 s.

unparseable_duration¶

Error. A fixed duration's seconds is not a positive number or time string.

seconds may be a number or a string such as "90s", "5m", "1h30m". A string that does not parse ("soon") or a negative one is reported here; the schema accepts any string.

Example. Merged over the base program:

{
  "tracks": [
    {
      "trackId": "main",
      "name": "Main",
      "steps": [
        {
          "stepId": "prep",
          "name": "Prep",
          "duration": { "type": "fixed", "seconds": "soon" },
          "startTrigger": { "type": "programStart" }
        }
      ]
    }
  ]
}

Fix. Use a number of seconds or a time string like "5m" or "1h30m".

Python. Python reports nothing for it.

variable_min_gt_max¶

Error. A variable duration's minSeconds is greater than its maxSeconds.

A variable step can end anywhere between minSeconds and maxSeconds; the bounds are the wrong way round.

Example. Merged over the base program:

{
  "tracks": [
    {
      "trackId": "main",
      "name": "Main",
      "steps": [
        {
          "stepId": "prep",
          "name": "Prep",
          "duration": {
            "type": "variable",
            "minSeconds": 600,
            "maxSeconds": 300,
            "defaultSeconds": 450
          },
          "startTrigger": { "type": "programStart" }
        }
      ]
    }
  ]
}

Fix. Swap the bounds so minSeconds <= maxSeconds.

Python. Python reports nothing for it.

variable_without_default¶

Warning. A variable duration has no defaultSeconds; planning uses maxSeconds.

Previews, the makespan and the analyzer place a variable step at defaultSeconds; without it they use maxSeconds, the worst case.

Example. Merged over the base program:

{
  "tracks": [
    {
      "trackId": "main",
      "name": "Main",
      "steps": [
        {
          "stepId": "prep",
          "name": "Prep",
          "duration": { "type": "variable", "minSeconds": 300, "maxSeconds": 600 },
          "startTrigger": { "type": "programStart" }
        }
      ]
    }
  ]
}

Fix. Add defaultSeconds (the expected time).

Python. Python reports nothing for it.

negative_offset_on_fixed¶

Warning. A negative offset counts down into a step that is not indefinite.

A negative offsetSeconds on afterStep starts this step before the referenced step ends. The live runner can only honour that when the referenced step is indefinite (its end is announced, so the countdown has an anchor); against a fixed or variable step it is ignored at run time.

Example. Merged over the base program:

{
  "tracks": [
    {
      "trackId": "main",
      "name": "Main",
      "steps": [
        {
          "stepId": "prep",
          "name": "Prep",
          "duration": { "type": "fixed", "seconds": 600 },
          "startTrigger": { "type": "programStart" }
        },
        {
          "stepId": "cook",
          "name": "Cook",
          "duration": { "type": "fixed", "seconds": 300 },
          "startTrigger": {
            "type": "afterStep",
            "stepId": "prep",
            "offsetSeconds": -120
          }
        }
      ]
    }
  ]
}

The two steps overlap, so track_overlap is reported too; put them in separate tracks to see the warning alone.

Fix. Give the referenced step duration.type "indefinite", or use a positive offset from event "start".

Python. Python reports negative_offset, as an error. An error in Python, which also rejects a negative offset on any trigger other than afterStep / afterStepWithBuffer.

dependency_cycle¶

Error. Steps wait for each other in a cycle.

Each step in the cycle waits (directly or transitively) for itself, so none of them can be scheduled. Reported once per step left unscheduled whose references all exist.

Example. Merged over the base program:

{
  "tracks": [
    {
      "trackId": "main",
      "name": "Main",
      "steps": [
        {
          "stepId": "prep",
          "name": "Prep",
          "duration": { "type": "fixed", "seconds": 300 },
          "startTrigger": { "type": "afterStep", "stepId": "cook" }
        }
      ]
    },
    {
      "trackId": "side",
      "name": "Side",
      "steps": [
        {
          "stepId": "cook",
          "name": "Cook",
          "duration": { "type": "fixed", "seconds": 300 },
          "startTrigger": { "type": "afterStep", "stepId": "prep" }
        }
      ]
    }
  ]
}

Fix. Break the cycle: start one of the steps from programStart or from a step outside the cycle.

Python. Python reports nothing for it. Python reports nothing; the steps are left unscheduled.

track_overlap¶

Error. Two steps in one track overlap in time.

Steps in a track run one after another (a track is one person, machine or lane). Two steps whose resolved times overlap usually lack an afterStep chain. Steps on different choice branches are exempt.

Example. Merged over the base program:

{
  "tracks": [
    {
      "trackId": "main",
      "name": "Main",
      "steps": [
        {
          "stepId": "prep",
          "name": "Prep",
          "duration": { "type": "fixed", "seconds": 300 },
          "startTrigger": { "type": "programStart" }
        },
        {
          "stepId": "cook",
          "name": "Cook",
          "duration": { "type": "fixed", "seconds": 300 },
          "startTrigger": { "type": "programStart" }
        }
      ]
    }
  ]
}

Fix. Chain the later step with {"type": "afterStep", "stepId": ""}, or move it to its own track if it really runs in parallel.

Python. Python reports track_overlap.

tracks_finish_far_apart¶

Warning. Some tracks finish long before the last one.

At least one track ends more than 30 minutes (or half the makespan, whichever is more) before the program does. Often fine; but if everything should be ready together, the early tracks start too soon.

Example. Merged over the base program:

{
  "tracks": [
    {
      "trackId": "main",
      "name": "Main",
      "steps": [
        {
          "stepId": "prep",
          "name": "Prep",
          "duration": { "type": "fixed", "seconds": 7200 },
          "startTrigger": { "type": "programStart" }
        }
      ]
    },
    {
      "trackId": "side",
      "name": "Side",
      "steps": [
        {
          "stepId": "cook",
          "name": "Cook",
          "duration": { "type": "fixed", "seconds": 600 },
          "startTrigger": { "type": "programStart" }
        }
      ]
    }
  ]
}

Fix. Delay the early tracks with programStartOffset or afterStep so they converge at the end, or ignore it when finishing apart is intended.

Python. Python reports nothing for it.

Resources¶

Tasks and resourceConstraints.

bad_resource_constraint¶

Error. A resource constraint has an empty task name.

Each entry of resourceConstraints limits one task type. A missing task is a schema_required finding; an empty string is reported here.

Example. Merged over the base program:

{ "resourceConstraints": [{ "task": "", "maxConcurrent": 1 }] }

Fix. Set task to the task name the steps use, or remove the entry.

Python. Python reports nothing for it.

duplicate_constraint¶

Warning. Two resource constraints name the same task.

Only one limit can apply to a task; which one wins depends on the reader.

Example. Merged over the base program:

{
  "tracks": [
    {
      "trackId": "main",
      "name": "Main",
      "steps": [
        {
          "stepId": "prep",
          "name": "Prep",
          "duration": { "type": "fixed", "seconds": 300 },
          "startTrigger": { "type": "programStart" },
          "task": "oven"
        }
      ]
    }
  ],
  "resourceConstraints": [
    { "task": "oven", "maxConcurrent": 1 },
    { "task": "oven", "maxConcurrent": 2 }
  ]
}

Fix. Keep one constraint per task.

Python. Python reports nothing for it.

bad_max_concurrent¶

Error. A resource constraint's maxConcurrent is not an integer >= 1.

The schema reports a bad maxConcurrent itself (schema_minimum, schema_type, schema_required), and this check stays quiet where it has. A program with an instances or replicates error (an E_* code) is checked against the schema as written, and those schema findings do not quiet the checks that follow, so this code is reported next to the schema's.

Example. Merged over the base program:

{
  "schemaVersion": "0.3.0-alpha",
  "tracks": [
    {
      "trackId": "main",
      "name": "Main",
      "steps": [
        {
          "stepId": "mix",
          "name": "Mix",
          "duration": { "type": "fixed", "seconds": 300 },
          "startTrigger": { "type": "programStart" }
        },
        {
          "stepId": "cool",
          "name": "Cool",
          "duration": { "type": "fixed", "seconds": 300 },
          "startTrigger": { "type": "afterStep", "stepId": "mix", "instances": "each" }
        }
      ]
    }
  ],
  "resourceConstraints": [{ "task": "oven", "maxConcurrent": 0 }]
}

Also emits E_INSTANCES_ON_SINGLE, schema_minimum and unused_constraint.

Fix. Set maxConcurrent to a whole number of at least 1.

Python. Python reports nothing for it.

task_not_constrained¶

Error or Warning. A task used by steps has no resource constraint.

Every task named by a step (task, tasks, taskResources, buffer taskResources) needs an entry in resourceConstraints, so the runner knows how many can run at once. It is an error, unless the program names an environment or actors, which may supply the constraint: then it is a warning.

Example 1 (error). Merged over the base program:

{
  "tracks": [
    {
      "trackId": "main",
      "name": "Main",
      "steps": [
        {
          "stepId": "prep",
          "name": "Prep",
          "duration": { "type": "fixed", "seconds": 300 },
          "startTrigger": { "type": "programStart" },
          "task": "oven"
        }
      ]
    }
  ]
}

Example 2 (warning). Merged over the base program:

{
  "tracks": [
    {
      "trackId": "main",
      "name": "Main",
      "steps": [
        {
          "stepId": "prep",
          "name": "Prep",
          "duration": { "type": "fixed", "seconds": 300 },
          "startTrigger": { "type": "programStart" },
          "task": "oven"
        }
      ]
    }
  ],
  "actors": 2
}

Fix. Add {"task": "", "maxConcurrent": N} to resourceConstraints.

Python. Python reports nothing for it by default. rhylthyme validate --strict reports task_not_constrained, as an error. That includes a program that names an environment or actors, where validateProgram reports a warning. The library (validate_program_structured) has no strict mode.

unused_constraint¶

Warning. A resource constraint names a task no step uses.

Usually a typo in the task name on the constraint or on the steps.

Example. Merged over the base program:

{ "resourceConstraints": [{ "task": "oven", "maxConcurrent": 1 }] }

Fix. Remove the constraint, or set task on the steps that use it.

Python. Python reports nothing for it.

Instances and replicates¶

Schema 0.3.0-alpha instances triggers, replicates and maxInFlight, and replicate expansion.