@opentrons/shared-data 0.0.0-alpha.2

package/protocol/schemas/5.json

@@ -0,0 +1,701 @@
+{
+  "$id": "opentronsProtocolSchemaV5",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+
+  "definitions": {
+    "pipetteName": {
+      "description": "Name of a pipette. Does not contain info about specific model/version. Should match keys in pipetteNameSpecs.json file",
+      "type": "string"
+    },
+
+    "moduleOnlyParams": {
+      "required": ["module"],
+      "additionalProperties": false,
+      "properties": {
+        "module": {
+          "type": "string"
+        }
+      }
+    },
+
+    "mmOffset": {
+      "description": "Millimeters for pipette location offsets",
+      "type": "number"
+    },
+
+    "offsetFromBottomMm": {
+      "description": "Offset from bottom of well in millimeters",
+      "required": ["offsetFromBottomMm"],
+      "properties": {
+        "offsetFromBottomMm": { "$ref": "#/definitions/mmOffset" }
+      }
+    },
+
+    "pipetteAccessParams": {
+      "required": ["pipette", "labware", "well"],
+      "properties": {
+        "pipette": {
+          "type": "string"
+        },
+        "labware": {
+          "type": "string"
+        },
+        "well": {
+          "type": "string"
+        }
+      }
+    },
+
+    "volumeParams": {
+      "required": ["volume"],
+      "volume": {
+        "type": "number"
+      }
+    },
+
+    "flowRate": {
+      "required": ["flowRate"],
+      "properties": {
+        "flowRate": {
+          "description": "Flow rate in uL/sec. Must be greater than 0",
+          "type": "number",
+          "minimum": 0
+        }
+      }
+    },
+
+    "slot": {
+      "description": "string '1'-'12', or special string 'span7_8_10_11' signify it's a slot on the OT-2 deck. If it's a UUID, it's the slot on the module referenced by that ID.",
+      "type": "string"
+    }
+  },
+
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "$otSharedSchema",
+    "schemaVersion",
+    "metadata",
+    "robot",
+    "pipettes",
+    "labware",
+    "labwareDefinitions",
+    "commands"
+  ],
+  "properties": {
+    "$otSharedSchema": {
+      "description": "The path to a valid Opentrons shared schema relative to the shared-data directory, without its extension.",
+      "enum": ["#/protocol/schemas/5"]
+    },
+
+    "schemaVersion": {
+      "description": "Schema version of a protocol is a single integer",
+      "enum": [5]
+    },
+
+    "metadata": {
+      "description": "Optional metadata about the protocol",
+      "type": "object",
+
+      "properties": {
+        "protocolName": {
+          "description": "A short, human-readable name for the protocol",
+          "type": "string"
+        },
+        "author": {
+          "description": "The author or organization who created the protocol",
+          "type": "string"
+        },
+        "description": {
+          "description": "A text description of the protocol.",
+          "type": ["string", "null"]
+        },
+
+        "created": {
+          "description": "UNIX timestamp when this file was created",
+          "type": "number"
+        },
+        "lastModified": {
+          "description": "UNIX timestamp when this file was last modified",
+          "type": ["number", "null"]
+        },
+
+        "category": {
+          "description": "Category of protocol (eg, \"Basic Pipetting\")",
+          "type": ["string", "null"]
+        },
+        "subcategory": {
+          "description": "Subcategory of protocol (eg, \"Cell Plating\")",
+          "type": ["string", "null"]
+        },
+        "tags": {
+          "description": "Tags to be used in searching for this protocol",
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
+
+    "designerApplication": {
+      "description": "Optional data & metadata not required to execute the protocol, used by the application that created this protocol",
+      "type": "object",
+      "properties": {
+        "name": {
+          "description": "Name of the application that created the protocol. Should be namespaced under the organization or individual who owns the organization, eg \"opentrons/protocol-designer\"",
+          "type": "string"
+        },
+        "version": {
+          "description": "Version of the application that created the protocol",
+          "type": "string"
+        },
+        "data": {
+          "description": "Any data used by the application that created this protocol",
+          "type": "object"
+        }
+      }
+    },
+
+    "robot": {
+      "required": ["model"],
+      "properties": {
+        "model": {
+          "description": "Model of the robot this protocol is written for (currently only OT-2 Standard is supported)",
+          "type": "string",
+          "enum": ["OT-2 Standard"]
+        }
+      }
+    },
+
+    "pipettes": {
+      "description": "The pipettes used in this protocol, keyed by an arbitrary unique ID",
+      "additionalProperties": false,
+      "patternProperties": {
+        ".+": {
+          "description": "Fields describing an individual pipette",
+          "type": "object",
+          "required": ["mount", "name"],
+          "additionalProperties": false,
+          "properties": {
+            "mount": {
+              "description": "Where the pipette is mounted",
+              "type": "string",
+              "enum": ["left", "right"]
+            },
+            "name": {
+              "$ref": "#/definitions/pipetteName"
+            }
+          }
+        }
+      }
+    },
+
+    "labwareDefinitions": {
+      "description": "All labware definitions used by labware in this protocol, keyed by UUID",
+      "patternProperties": {
+        ".+": {
+          "$ref": "opentronsLabwareSchemaV2"
+        }
+      }
+    },
+
+    "labware": {
+      "description": "All types of labware used in this protocol, and references to their definitions",
+      "patternProperties": {
+        ".+": {
+          "description": "Fields describing a single labware on the deck",
+          "type": "object",
+          "required": ["slot", "definitionId"],
+          "additionalProperties": false,
+          "properties": {
+            "slot": { "$ref": "#/definitions/slot" },
+            "definitionId": {
+              "description": "reference to this labware's ID in \"labwareDefinitions\"",
+              "type": "string"
+            },
+            "displayName": {
+              "description": "An optional human-readable nickname for this labware. Eg \"Buffer Trough\"",
+              "type": "string"
+            }
+          }
+        }
+      }
+    },
+
+    "modules": {
+      "description": "All modules used in this protocol",
+      "patternProperties": {
+        ".+": {
+          "description": "Fields describing a single module on the deck",
+          "type": "object",
+          "required": ["slot", "model"],
+          "additionalProperties": false,
+          "properties": {
+            "slot": { "$ref": "#/definitions/slot" },
+            "model": {
+              "description": "model of module. Eg 'magneticModuleV1' or 'magneticModuleV2'. This should match a top-level key in shared-data/module/definitions/2.json",
+              "type": "string"
+            }
+          }
+        }
+      }
+    },
+
+    "commands": {
+      "description": "An array of command objects representing steps to be executed on the robot",
+      "type": "array",
+      "items": {
+        "anyOf": [
+          {
+            "description": "Aspirate / dispense / air gap commands",
+            "type": "object",
+            "required": ["command", "params"],
+            "additionalProperties": false,
+            "properties": {
+              "command": {
+                "enum": ["aspirate", "dispense", "airGap"]
+              },
+              "params": {
+                "allOf": [
+                  { "$ref": "#/definitions/flowRate" },
+                  { "$ref": "#/definitions/pipetteAccessParams" },
+                  { "$ref": "#/definitions/volumeParams" },
+                  { "$ref": "#/definitions/offsetFromBottomMm" }
+                ]
+              }
+            }
+          },
+
+          {
+            "description": "Blowout command",
+            "type": "object",
+            "required": ["command", "params"],
+            "additionalProperties": false,
+            "properties": {
+              "command": {
+                "enum": ["blowout"]
+              },
+              "params": {
+                "allOf": [
+                  { "$ref": "#/definitions/flowRate" },
+                  { "$ref": "#/definitions/pipetteAccessParams" },
+                  { "$ref": "#/definitions/offsetFromBottomMm" }
+                ]
+              }
+            }
+          },
+
+          {
+            "description": "Touch tip commands",
+            "type": "object",
+            "required": ["command", "params"],
+            "additionalProperties": false,
+            "properties": {
+              "command": {
+                "enum": ["touchTip"]
+              },
+              "params": {
+                "allOf": [
+                  { "$ref": "#/definitions/pipetteAccessParams" },
+                  { "$ref": "#/definitions/offsetFromBottomMm" }
+                ]
+              }
+            }
+          },
+
+          {
+            "description": "Pick up tip / drop tip commands",
+            "type": "object",
+            "required": ["command", "params"],
+            "additionalProperties": false,
+            "properties": {
+              "command": {
+                "enum": ["pickUpTip", "dropTip"]
+              },
+              "params": {
+                "allOf": [{ "$ref": "#/definitions/pipetteAccessParams" }]
+              }
+            }
+          },
+
+          {
+            "description": "Move to slot command. NOTE: this is an EXPERIMENTAL command, its behavior is subject to change in future releases.",
+            "type": "object",
+            "required": ["command", "params"],
+            "additionalProperties": false,
+            "properties": {
+              "command": { "enum": ["moveToSlot"] },
+              "params": {
+                "type": "object",
+                "required": ["pipette", "slot"],
+                "additionalProperties": false,
+                "properties": {
+                  "pipette": { "type": "string" },
+                  "slot": { "$ref": "#/definitions/slot" },
+                  "offset": {
+                    "description": "Optional offset from slot bottom left corner, in mm",
+                    "type": "object",
+                    "required": ["x", "y", "z"],
+                    "properties": {
+                      "x": { "type": "number" },
+                      "y": { "type": "number" },
+                      "z": { "type": "number" }
+                    }
+                  },
+                  "minimumZHeight": {
+                    "description": "Optional minimal Z margin in mm. If this is larger than the API's default safe Z margin, it will make the arc higher. If it's smaller, it will have no effect. Specifying this for movements that would not arc (moving within the same well in the same labware) will cause an arc movement instead.",
+                    "type": "number",
+                    "minimum": 0
+                  },
+                  "forceDirect": {
+                    "description": "Default is false. If true, moving from one labware/well to another will not arc to the default safe z, but instead will move directly to the specified location. This will also force the 'minimumZHeight' param to be ignored. A 'direct' movement is in X/Y/Z simultaneously",
+                    "type": "boolean"
+                  }
+                }
+              }
+            }
+          },
+
+          {
+            "description": "Delay command",
+            "type": "object",
+            "required": ["command", "params"],
+            "additionalProperties": false,
+            "properties": {
+              "command": {
+                "enum": ["delay"]
+              },
+              "params": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["wait"],
+                "properties": {
+                  "wait": {
+                    "description": "either a number of seconds to wait (fractional values OK), or `true` to wait indefinitely until the user manually resumes the protocol",
+                    "anyOf": [{ "type": "number" }, { "enum": [true] }]
+                  },
+                  "message": {
+                    "description": "optional message describing the delay"
+                  }
+                }
+              }
+            }
+          },
+
+          {
+            "description": "Magnetic module engage command. Engages magnet to specified height",
+            "type": "object",
+            "required": ["command", "params"],
+            "additionalProperties": false,
+            "properties": {
+              "command": {
+                "enum": ["magneticModule/engageMagnet"]
+              },
+              "params": {
+                "required": ["module", "engageHeight"],
+                "additionalProperties": false,
+                "properties": {
+                  "engageHeight": {
+                    "description": "Height in mm(*) from bottom plane of labware (above if positive, below if negative). *NOTE: for magneticModuleV1 (aka GEN1), these are not true mm but an arbitrary unit equal to 0.5mm. So `engageHeight: 2` means 1mm above the labware plane if the command is for a GEN1 magnetic module, but would mean 2mm above the labware plane for GEN2 module",
+                    "type": "number"
+                  },
+                  "module": {
+                    "type": "string"
+                  }
+                }
+              }
+            }
+          },
+
+          {
+            "description": "Magnetic module disengage command. Moves magnet down to disengaged (home) position",
+            "type": "object",
+            "required": ["command", "params"],
+            "additionalProperties": false,
+            "properties": {
+              "command": {
+                "enum": ["magneticModule/disengageMagnet"]
+              },
+              "params": {
+                "$ref": "#/definitions/moduleOnlyParams"
+              }
+            }
+          },
+
+          {
+            "description": "Temperature module set target temperature command. Module will begin moving to the target temperature. This command is non-blocking, it does not delay until the temperature is reached.",
+            "type": "object",
+            "required": ["command", "params"],
+            "additionalProperties": false,
+            "properties": {
+              "command": { "enum": ["temperatureModule/setTargetTemperature"] },
+              "params": {
+                "required": ["module", "temperature"],
+                "additionalProperties": false,
+                "properties": {
+                  "module": { "type": "string" },
+                  "temperature": { "type": "number" }
+                }
+              }
+            }
+          },
+
+          {
+            "description": "Temperature module await temperature command. Delay further protocol execution until the specified temperature is reached.",
+            "type": "object",
+            "required": ["command", "params"],
+            "additionalProperties": false,
+            "properties": {
+              "command": { "enum": ["temperatureModule/awaitTemperature"] },
+              "params": {
+                "required": ["module", "temperature"],
+                "additionalProperties": false,
+                "properties": {
+                  "module": { "type": "string" },
+                  "temperature": { "type": "number" }
+                }
+              }
+            }
+          },
+
+          {
+            "description": "Temperature module deactivate command. Module will stop actively controlling its temperature and drift to ambient temperature.",
+            "type": "object",
+            "required": ["command", "params"],
+            "additionalProperties": false,
+            "properties": {
+              "command": { "enum": ["temperatureModule/deactivate"] },
+              "params": {
+                "$ref": "#/definitions/moduleOnlyParams"
+              }
+            }
+          },
+
+          {
+            "description": "Thermocycler set target block temperature command. Lid will begin moving to the target temperature. This command is non-blocking, it does not delay until the temperature is reached.",
+            "type": "object",
+            "required": ["command", "params"],
+            "additionalProperties": false,
+            "properties": {
+              "command": { "enum": ["thermocycler/setTargetBlockTemperature"] },
+              "params": {
+                "required": ["module", "temperature"],
+                "additionalProperties": false,
+                "properties": {
+                  "module": { "type": "string" },
+                  "temperature": { "type": "number" },
+                  "volume": {
+                    "type": "number"
+                  }
+                }
+              }
+            }
+          },
+
+          {
+            "description": "Thermocycler set target lid temperature command. Lid will begin moving to the target temperature. This command is non-blocking, it does not delay until the temperature is reached.",
+            "type": "object",
+            "required": ["command", "params"],
+            "additionalProperties": false,
+            "properties": {
+              "command": { "enum": ["thermocycler/setTargetLidTemperature"] },
+              "params": {
+                "required": ["module", "temperature"],
+                "additionalProperties": false,
+                "properties": {
+                  "module": { "type": "string" },
+                  "temperature": { "type": "number" }
+                }
+              }
+            }
+          },
+
+          {
+            "description": "Thermocycler await block temperature command. Delay further protocol execution until the specified temperature is reached.",
+            "type": "object",
+            "required": ["command", "params"],
+            "additionalProperties": false,
+            "properties": {
+              "command": { "enum": ["thermocycler/awaitBlockTemperature"] },
+              "params": {
+                "required": ["module", "temperature"],
+                "additionalProperties": false,
+                "properties": {
+                  "module": { "type": "string" },
+                  "temperature": { "type": "number" }
+                }
+              }
+            }
+          },
+
+          {
+            "description": "Thermocycler await lid temperature command. Delay further protocol execution until the specified temperature is reached.",
+            "type": "object",
+            "required": ["command", "params"],
+            "additionalProperties": false,
+            "properties": {
+              "command": { "enum": ["thermocycler/awaitLidTemperature"] },
+              "params": {
+                "required": ["module", "temperature"],
+                "additionalProperties": false,
+                "properties": {
+                  "module": { "type": "string" },
+                  "temperature": { "type": "number" }
+                }
+              }
+            }
+          },
+
+          {
+            "description": "Thermocycler deactivate block command. Module will stop actively controlling its block temperature.",
+            "type": "object",
+            "required": ["command", "params"],
+            "additionalProperties": false,
+            "properties": {
+              "command": { "enum": ["thermocycler/deactivateBlock"] },
+              "params": {
+                "$ref": "#/definitions/moduleOnlyParams"
+              }
+            }
+          },
+
+          {
+            "description": "Thermocycler deactivate lid command. Module will stop actively controlling its lid temperature.",
+            "type": "object",
+            "required": ["command", "params"],
+            "additionalProperties": false,
+            "properties": {
+              "command": { "enum": ["thermocycler/deactivateLid"] },
+              "params": {
+                "$ref": "#/definitions/moduleOnlyParams"
+              }
+            }
+          },
+
+          {
+            "description": "Thermocycler open lid command. This command will block until the lid is fully open.",
+            "type": "object",
+            "required": ["command", "params"],
+            "additionalProperties": false,
+            "properties": {
+              "command": { "enum": ["thermocycler/openLid"] },
+              "params": {
+                "$ref": "#/definitions/moduleOnlyParams"
+              }
+            }
+          },
+
+          {
+            "description": "Thermocycler close lid command. This command will block until the lid is fully closed.",
+            "type": "object",
+            "required": ["command", "params"],
+            "additionalProperties": false,
+            "properties": {
+              "command": { "enum": ["thermocycler/closeLid"] },
+              "params": {
+                "$ref": "#/definitions/moduleOnlyParams"
+              }
+            }
+          },
+
+          {
+            "description": "Thermocycler run profile command. Begin running the specified profile steps on the thermocycler. This command is non-blocking, it does not delay protocol execution outside of thermocycler steps. No more thermocycler commands should be given until a 'thermocycler/awaitProfileComplete' command is executed.",
+            "type": "object",
+            "required": ["command", "params"],
+            "additionalProperties": false,
+            "properties": {
+              "command": { "enum": ["thermocycler/runProfile"] },
+              "params": {
+                "type": "object",
+                "required": ["module", "profile", "volume"],
+                "additionalProperties": false,
+                "properties": {
+                  "module": { "type": "string" },
+                  "profile": {
+                    "type": "array",
+                    "items": {
+                      "type": "object",
+                      "required": ["temperature", "holdTime"],
+                      "additionalProperties": false,
+                      "properties": {
+                        "temperature": {
+                          "description": "Target temperature of profile step",
+                          "type": "number"
+                        },
+                        "holdTime": {
+                          "description": "Time (in seconds) to hold once temperature is reached",
+                          "type": "number"
+                        }
+                      }
+                    }
+                  },
+                  "volume": {
+                    "type": "number"
+                  }
+                }
+              }
+            }
+          },
+
+          {
+            "description": "Thermocycler await profile complete command. Blocks further protocol execution until profile execution is complete.",
+            "type": "object",
+            "required": ["command", "params"],
+            "additionalProperties": false,
+            "properties": {
+              "command": { "enum": ["thermocycler/awaitProfileComplete"] },
+              "params": {
+                "$ref": "#/definitions/moduleOnlyParams"
+              }
+            }
+          },
+
+          {
+            "description": "Move to well command. Move the pipette's critical point to the specified well in a labware, with an optional offset. The pipette's critical point is a reference point on the pipette. The critical point can be one of the following: (1) Single-channel pipette with no tip: end of nozzle. (2) Multi-channel pipette with no tip: end of backmost nozzle. (3) Single-channel pipette with a tip: end of tip. (4) Multi-channel pipette with tip: end of tip on backmost nozzle.",
+            "type": "object",
+            "required": ["command", "params"],
+            "additionalProperties": false,
+            "properties": {
+              "command": { "enum": ["moveToWell"] },
+              "params": {
+                "type": "object",
+                "required": ["pipette", "labware", "well"],
+                "additionalProperties": false,
+                "properties": {
+                  "pipette": { "type": "string" },
+                  "labware": { "type": "string" },
+                  "well": { "type": "string" },
+                  "offset": {
+                    "description": "Optional offset from well bottom center, in mm",
+                    "type": "object",
+                    "required": ["x", "y", "z"],
+                    "properties": {
+                      "x": { "type": "number" },
+                      "y": { "type": "number" },
+                      "z": { "type": "number" }
+                    }
+                  },
+                  "minimumZHeight": {
+                    "description": "Optional minimal Z margin in mm. If this is larger than the API's default safe Z margin, it will make the arc higher. If it's smaller, it will have no effect. Specifying this for movements that would not arc (moving within the same well in the same labware) will cause an arc movement instead.",
+                    "type": "number",
+                    "minimum": 0
+                  },
+                  "forceDirect": {
+                    "description": "Default is false. If true, moving from one labware/well to another will not arc to the default safe z, but instead will move directly to the specified location. This will also force the 'minimumZHeight' param to be ignored. A 'direct' movement is in X/Y/Z simultaneously",
+                    "type": "boolean"
+                  }
+                }
+              }
+            }
+          }
+        ]
+      }
+    },
+
+    "commandAnnotations": {
+      "description": "An optional object of annotations associated with commands. Its usage has not yet been defined, so its shape is not enforced by this schema.",
+      "type": "object"
+    }
+  }
+}