Opentrons · Schema

Opentrons Command

JSON Schema for an Opentrons protocol command, representing an atomic liquid handling or robot control instruction such as aspirate, dispense, pick up tip, move, or module control.

Lab AutomationLiquid HandlingRoboticsBiologyLife SciencesProtocol ManagementHardware ControlOpen Source

Properties

Name	Type	Description
id	string	Unique identifier for the command
createdAt	string	When the command was created
startedAt	stringnull	When execution of the command began
completedAt	stringnull	When execution of the command completed
commandType	string	The type of command (e.g., aspirate, dispense, pickUpTip, dropTip, moveToWell, moveToCoordinates, home, loadLabware, loadPipette, loadModule)
params	object	Command-specific parameters
result	objectnull	Command-specific result data returned after execution
status	string	The current execution status of the command
error	objectnull	Error details if the command failed
intent	string	The intent of the command: setup commands run before the protocol, protocol commands are part of the protocol, fixit commands are used for error recovery
key	stringnull	Optional key for identifying this command, used for error recovery
notes	array	Informational notes about the command execution

View JSON Schema on GitHub

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12",
  "$id": "https://raw.githubusercontent.com/api-evangelist/opentrons/main/json-schema/opentrons-command-schema.json",
  "title": "Opentrons Command",
  "description": "JSON Schema for an Opentrons protocol command, representing an atomic liquid handling or robot control instruction such as aspirate, dispense, pick up tip, move, or module control.",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the command"
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "description": "When the command was created"
    },
    "startedAt": {
      "type": ["string", "null"],
      "format": "date-time",
      "description": "When execution of the command began"
    },
    "completedAt": {
      "type": ["string", "null"],
      "format": "date-time",
      "description": "When execution of the command completed"
    },
    "commandType": {
      "type": "string",
      "description": "The type of command (e.g., aspirate, dispense, pickUpTip, dropTip, moveToWell, moveToCoordinates, home, loadLabware, loadPipette, loadModule)",
      "examples": [
        "aspirate",
        "aspirateInPlace",
        "dispense",
        "dispenseInPlace",
        "pickUpTip",
        "dropTip",
        "dropTipInPlace",
        "moveToWell",
        "moveToCoordinates",
        "moveRelative",
        "home",
        "loadLabware",
        "reloadLabware",
        "loadPipette",
        "loadModule",
        "loadLiquid",
        "blowout",
        "blowOutInPlace",
        "touchTip",
        "mix",
        "configureForVolume",
        "prepareToAspirate",
        "waitForDuration",
        "waitForResume",
        "comment",
        "setRailLights",
        "moveLabware",
        "heaterShaker/setTargetTemperature",
        "heaterShaker/setAndWaitForShakeSpeed",
        "heaterShaker/openLabwareLatch",
        "heaterShaker/closeLabwareLatch",
        "temperatureModule/setTargetTemperature",
        "temperatureModule/waitForTemperature",
        "thermocycler/setTargetBlockTemperature",
        "thermocycler/runProfile",
        "magneticModule/engage",
        "magneticModule/disengage",
        "absorbanceReader/initialize",
        "absorbanceReader/read"
      ]
    },
    "params": {
      "type": "object",
      "description": "Command-specific parameters",
      "additionalProperties": true
    },
    "result": {
      "type": ["object", "null"],
      "description": "Command-specific result data returned after execution",
      "additionalProperties": true
    },
    "status": {
      "type": "string",
      "enum": ["queued", "running", "succeeded", "failed"],
      "description": "The current execution status of the command"
    },
    "error": {
      "type": ["object", "null"],
      "description": "Error details if the command failed"
    },
    "intent": {
      "type": "string",
      "enum": ["setup", "protocol", "fixit"],
      "description": "The intent of the command: setup commands run before the protocol, protocol commands are part of the protocol, fixit commands are used for error recovery"
    },
    "key": {
      "type": ["string", "null"],
      "description": "Optional key for identifying this command, used for error recovery"
    },
    "notes": {
      "type": "array",
      "description": "Informational notes about the command execution",
      "items": {
        "type": "object"
      }
    }
  },
  "required": ["id", "createdAt", "commandType", "params", "status"],
  "$defs": {
    "WellLocation": {
      "type": "object",
      "description": "A location within a labware well",
      "properties": {
        "origin": {
          "type": "string",
          "enum": ["top", "bottom", "center", "meniscus"],
          "description": "The reference point within the well"
        },
        "offset": {
          "type": "object",
          "description": "Offset from the origin in millimeters",
          "properties": {
            "x": { "type": "number" },
            "y": { "type": "number" },
            "z": { "type": "number" }
          }
        },
        "volumeOffset": {
          "type": ["string", "number"],
          "description": "Volume-based offset from the meniscus"
        }
      }
    },
    "AspirateParams": {
      "type": "object",
      "description": "Parameters for an aspirate command",
      "properties": {
        "pipetteId": {
          "type": "string",
          "description": "The ID of the pipette to use"
        },
        "labwareId": {
          "type": "string",
          "description": "The ID of the labware containing the well"
        },
        "wellName": {
          "type": "string",
          "description": "The name of the well (e.g., 'A1', 'B2')"
        },
        "wellLocation": {
          "$ref": "#/$defs/WellLocation"
        },
        "volume": {
          "type": "number",
          "description": "Volume to aspirate in microliters"
        },
        "flowRate": {
          "type": "number",
          "description": "Flow rate in microliters per second"
        }
      },
      "required": ["pipetteId", "labwareId", "wellName", "volume", "flowRate"]
    },
    "DispenseParams": {
      "type": "object",
      "description": "Parameters for a dispense command",
      "properties": {
        "pipetteId": {
          "type": "string"
        },
        "labwareId": {
          "type": "string"
        },
        "wellName": {
          "type": "string"
        },
        "wellLocation": {
          "$ref": "#/$defs/WellLocation"
        },
        "volume": {
          "type": "number",
          "description": "Volume to dispense in microliters"
        },
        "flowRate": {
          "type": "number",
          "description": "Flow rate in microliters per second"
        },
        "pushOut": {
          "type": "number",
          "description": "Extra volume to push out after dispense in microliters"
        }
      },
      "required": ["pipetteId", "labwareId", "wellName", "volume", "flowRate"]
    }
  }
}