@opentrons/shared-data 0.1.6-alpha.9 → 0.1.7-alpha.1

package/lib/labware/schemas/3.json

@@ -41,7 +41,9 @@
                 "wellPlate",
                 "aluminumBlock",
                 "adapter",
-                "other"
+                "other",
+                "lid",
+                "system"
             ]
         },
         "safeString": {
@@ -49,7 +51,20 @@
             "type": "string",
             "pattern": "^[a-z0-9._]+$"
         },
-        "coordinates": {
+        "vector2D": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["x", "y"],
+            "properties": {
+                "x": {
+                    "type": "number"
+                },
+                "y": {
+                    "type": "number"
+                }
+            }
+        },
+        "vector3D": {
             "type": "object",
             "additionalProperties": false,
             "required": ["x", "y", "z"],
@@ -65,6 +80,151 @@
                 }
             }
         },
+        "axisAlignedBoundingBox2D": {
+            "type": "object",
+            "required": ["backLeft", "frontRight"],
+            "additionalProperties": false,
+            "properties": {
+                "backLeft": {
+                    "description": "(-x, +y) relative to the labware origin.",
+                    "$ref": "#/definitions/vector2D"
+                },
+                "frontRight": {
+                    "description": "(+x, -y) relative to the labware origin.",
+                    "$ref": "#/definitions/vector2D"
+                }
+            }
+        },
+        "axisAlignedBoundingBox3D": {
+            "type": "object",
+            "required": ["backLeftBottom", "frontRightTop"],
+            "additionalProperties": false,
+            "properties": {
+                "backLeftBottom": {
+                    "description": "(-x, +y, -z) relative to the labware origin.",
+                    "$ref": "#/definitions/vector3D"
+                },
+                "frontRightTop": {
+                    "description": "(+x, -y, +z) relative to the labware origin.",
+                    "$ref": "#/definitions/vector3D"
+                }
+            }
+        },
+        "pickUpAndDropOffsets": {
+            "type": "object",
+            "required": ["pickUpOffset", "dropOffset"],
+            "properties": {
+                "pickUpOffset": {
+                    "$ref": "#/definitions/vector3D",
+                    "description": "Offset added to calculate pick-up coordinates."
+                },
+                "dropOffset": {
+                    "$ref": "#/definitions/vector3D",
+                    "description": "Offset added to calculate drop coordinates."
+                }
+            }
+        },
+        "well": {
+            "anyOf": [
+                { "$ref": "#/definitions/rectangularWell" },
+                { "$ref": "#/definitions/circularWell" }
+            ]
+        },
+        "rectangularWell": {
+            "type": "object",
+            "required": [
+                "shape",
+                "depth",
+                "totalLiquidVolume",
+                "x",
+                "y",
+                "z",
+                "xDimension",
+                "yDimension"
+            ],
+            "$comment": "The properties with a subschema of `true` ('always pass') are defined in wellCommon. They need to be mentioned here for additionalProperties to work right, until we have JSON Schema 2019-09 and we can switch to unevaluatedProperties.",
+            "properties": {
+                "shape": {
+                    "const": "rectangular"
+                },
+                "depth": true,
+                "totalLiquidVolume": true,
+                "x": true,
+                "y": true,
+                "z": true,
+                "geometryDefinitionId": true,
+                "xDimension": {
+                    "description": "x dimension of rectangular wells",
+                    "$ref": "#/definitions/positiveNumber"
+                },
+                "yDimension": {
+                    "description": "y dimension of rectangular wells",
+                    "$ref": "#/definitions/positiveNumber"
+                }
+            },
+            "additionalProperties": false,
+            "allOf": [{ "$ref": "#/definitions/wellCommon" }]
+        },
+        "circularWell": {
+            "type": "object",
+            "required": [
+                "shape",
+                "depth",
+                "totalLiquidVolume",
+                "x",
+                "y",
+                "z",
+                "diameter"
+            ],
+            "$comment": "The properties with a subschema of `true` ('always pass') are defined in wellCommon. They need to be mentioned here for additionalProperties to work right, until we have JSON Schema 2019-09 and we can switch to unevaluatedProperties.",
+            "properties": {
+                "shape": {
+                    "const": "circular"
+                },
+                "depth": true,
+                "totalLiquidVolume": true,
+                "x": true,
+                "y": true,
+                "z": true,
+                "geometryDefinitionId": true,
+                "diameter": {
+                    "description": "diameter of circular wells",
+                    "$ref": "#/definitions/positiveNumber"
+                }
+            },
+            "additionalProperties": false,
+            "allOf": [{ "$ref": "#/definitions/wellCommon" }]
+        },
+        "wellCommon": {
+            "$comment": "These properties need to stay in sync with rectangularWell and circularWell. See comments there.",
+            "properties": {
+                "depth": {
+                    "description": "The distance between the top and bottom of this well. If the labware is a tip rack, this will be ignored in favor of tipLength, but the values should match.",
+                    "$ref": "#/definitions/positiveNumber"
+                },
+                "totalLiquidVolume": {
+                    "description": "Total well, tube, or tip volume in microliters",
+                    "$ref": "#/definitions/positiveNumber"
+                },
+                "x": {
+                    "description": "x location of center-bottom of well in reference to the labware origin",
+                    "$ref": "#/definitions/positiveNumber"
+                },
+                "y": {
+                    "description": "y location of center-bottom of well in reference to the labware origin",
+                    "type": "number",
+                    "maximum": 0
+                },
+                "z": {
+                    "description": "z location of center-bottom of well in reference to the labware origin",
+                    "$ref": "#/definitions/positiveNumber"
+                },
+                "geometryDefinitionId": {
+                    "description": "string id of the well's corresponding innerWellGeometry",
+                    "type": ["string", "null"]
+                }
+            }
+        },
         "SphericalSegment": {
             "type": "object",
             "description": "A partial sphere shaped section at the bottom of the well.",
@@ -76,19 +236,24 @@
                     "enum": ["spherical"]
                 },
                 "radiusOfCurvature": {
-                    "type": "number"
+                    "type": "number",
+                    "description": "radius of curvature of bottom subsection of wells"
                 },
                 "topHeight": {
-                    "type": "number"
+                    "type": "number",
+                    "description": "The depth of a spherical bottom of a well"
                 },
                 "bottomHeight": {
-                    "type": "number"
+                    "type": "number",
+                    "description": "Height of the bottom of the segment, must be 0.0"
                 },
                 "xCount": {
-                    "type": "integer"
+                    "type": "integer",
+                    "description": "Number of instances of this shape in the stackup, used for wells that have multiple sub-wells"
                 },
                 "yCount": {
-                    "type": "integer"
+                    "type": "integer",
+                    "description": "Number of instances of this shape in the stackup, used for wells that have multiple sub-wells"
                 }
             }
         },
@@ -108,22 +273,28 @@
                     "enum": ["conical"]
                 },
                 "bottomDiameter": {
-                    "type": "number"
+                    "type": "number",
+                    "description": "The diameter at the bottom cross-section of a circular frustum"
                 },
                 "topDiameter": {
-                    "type": "number"
+                    "type": "number",
+                    "description": "The diameter at the top cross-section of a circular frustum"
                 },
                 "topHeight": {
-                    "type": "number"
+                    "type": "number",
+                    "description": "The height at the top of a bounded subsection of a well, relative to the bottom of the well"
                 },
                 "bottomHeight": {
-                    "type": "number"
+                    "type": "number",
+                    "description": "The height at the bottom of a bounded subsection of a well, relative to the bottom of the well"
                 },
                 "xCount": {
-                    "type": "integer"
+                    "type": "integer",
+                    "description": "Number of instances of this shape in the stackup, used for wells that have multiple sub-wells"
                 },
                 "yCount": {
-                    "type": "integer"
+                    "type": "integer",
+                    "description": "Number of instances of this shape in the stackup, used for wells that have multiple sub-wells"
                 }
             }
         },
@@ -145,28 +316,36 @@
                     "enum": ["cuboidal"]
                 },
                 "bottomXDimension": {
-                    "type": "number"
+                    "type": "number",
+                    "description": "x dimension of the bottom cross-section of a rectangular frustum"
                 },
                 "bottomYDimension": {
-                    "type": "number"
+                    "type": "number",
+                    "description": "y dimension of the bottom cross-section of a rectangular frustum"
                 },
                 "topXDimension": {
-                    "type": "number"
+                    "type": "number",
+                    "description": "x dimension of the top cross-section of a rectangular frustum"
                 },
                 "topYDimension": {
-                    "type": "number"
+                    "type": "number",
+                    "description": "y dimension of the top cross-section of a rectangular frustum"
                 },
                 "topHeight": {
-                    "type": "number"
+                    "type": "number",
+                    "description": "The height at the top of a bounded subsection of a well, relative to the bottom of the well"
                 },
                 "bottomHeight": {
-                    "type": "number"
+                    "type": "number",
+                    "description": "The height at the bottom of a bounded subsection of a well, relative to the bottom of the well"
                 },
                 "xCount": {
-                    "type": "integer"
+                    "type": "integer",
+                    "description": "Number of instances of this shape in the stackup, used for wells that have multiple sub-wells"
                 },
                 "yCount": {
-                    "type": "integer"
+                    "type": "integer",
+                    "description": "Number of instances of this shape in the stackup, used for wells that have multiple sub-wells"
                 }
             }
         },
@@ -189,28 +368,36 @@
                 },
                 "bottomCrossSection": {
                     "type": "string",
-                    "enum": ["circular", "rectangular"]
+                    "enum": ["circular", "rectangular"],
+                    "description": "Denote if the shape is going from circular to rectangular or vise versa"
                 },
                 "circleDiameter": {
-                    "type": "number"
+                    "type": "number",
+                    "description": "diameter of the circular face of a truncated circular segment"
                 },
                 "rectangleXDimension": {
-                    "type": "number"
+                    "type": "number",
+                    "description": "x dimension of the rectangular face of a truncated circular segment"
                 },
                 "rectangleYDimension": {
-                    "type": "number"
+                    "type": "number",
+                    "description": "y dimension of the rectangular face of a truncated circular segment"
                 },
                 "topHeight": {
-                    "type": "number"
+                    "type": "number",
+                    "description": "The height at the top of a bounded subsection of a well, relative to the bottom of the well"
                 },
                 "bottomHeight": {
-                    "type": "number"
+                    "type": "number",
+                    "description": "The height at the bottom of a bounded subsection of a well, relative to the bottom of the well"
                 },
                 "xCount": {
-                    "type": "integer"
+                    "type": "integer",
+                    "description": "Number of instances of this shape in the stackup, used for wells that have multiple sub-wells"
                 },
                 "yCount": {
-                    "type": "integer"
+                    "type": "integer",
+                    "description": "Number of instances of this shape in the stackup, used for wells that have multiple sub-wells"
                 }
             }
         },
@@ -233,28 +420,36 @@
                 },
                 "bottomCrossSection": {
                     "type": "string",
-                    "enum": ["circular", "rectangular"]
+                    "enum": ["circular", "rectangular"],
+                    "description": "Denote if the shape is going from circular to rectangular or vise versa"
                 },
                 "circleDiameter": {
-                    "type": "number"
+                    "type": "number",
+                    "description": "diameter of the circular face of a rounded rectangular segment"
                 },
                 "rectangleXDimension": {
-                    "type": "number"
+                    "type": "number",
+                    "description": "x dimension of the rectangular face of a rounded rectangular segment"
                 },
                 "rectangleYDimension": {
-                    "type": "number"
+                    "type": "number",
+                    "description": "y dimension of the rectangular face of a rounded rectangular segment"
                 },
                 "topHeight": {
-                    "type": "number"
+                    "type": "number",
+                    "description": "The height at the top of a bounded subsection of a well, relative to the bottom"
                 },
                 "bottomHeight": {
-                    "type": "number"
+                    "type": "number",
+                    "description": "The height at the bottom of a bounded subsection of a well, relative to the bottom of the well"
                 },
                 "xCount": {
-                    "type": "integer"
+                    "type": "integer",
+                    "description": "Number of instances of this shape in the stackup, used for wells that have multiple sub-wells"
                 },
                 "yCount": {
-                    "type": "integer"
+                    "type": "integer",
+                    "description": "Number of instances of this shape in the stackup, used for wells that have multiple sub-wells"
                 }
             }
         },
@@ -263,8 +458,9 @@
             "required": ["sections"],
             "properties": {
                 "sections": {
-                    "description": "A list of all of the sections of the well that have a contiguous shape",
+                    "description": "A list of all of the sections of the well that have a contiguous shape. Must be ordered from top (highest z) to bottom (lowest z).",
                     "type": "array",
+                    "minItems": 1,
                     "items": {
                         "oneOf": [
                             {
@@ -291,19 +487,23 @@
     "type": "object",
     "additionalProperties": false,
     "required": [
+        "$otSharedSchema",
         "schemaVersion",
         "version",
         "namespace",
         "metadata",
         "brand",
         "parameters",
-        "cornerOffsetFromSlot",
         "ordering",
-        "dimensions",
+        "extents",
         "wells",
         "groups"
     ],
     "properties": {
+        "$otSharedSchema": {
+            "description": "The path to a valid Opentrons shared schema relative to the shared-data directory, without its extension.",
+            "enum": ["#/labware/schemas/3"]
+        },
         "schemaVersion": {
             "description": "Which schema version a labware is using",
             "type": "number",
@@ -392,6 +592,11 @@
                     "description": "Flag marking whether a labware is compatible by default with the Magnetic Module",
                     "type": "boolean"
                 },
+                "isDeckSlotCompatible": {
+                    "description": "Flag marking whether a labware is compatible by with being placed or loaded in a base deck slot, defaults to true.",
+                    "type": "boolean",
+                    "default": true
+                },
                 "magneticModuleEngageHeight": {
                     "description": "Distance to move magnetic module magnets to engage",
                     "$ref": "#/definitions/positiveNumber"
@@ -408,31 +613,19 @@
                 }
             }
         },
-        "cornerOffsetFromSlot": {
-            "type": "object",
-            "additionalProperties": false,
-            "description": "Distance from left-front-bottom corner of slot to left-front-bottom corner of labware bounding box. Used for labware that spans multiple slots. For labware that does not span multiple slots, x/y/z should all be zero.",
-            "required": ["x", "y", "z"],
-            "properties": {
-                "x": { "type": "number" },
-                "y": { "type": "number" },
-                "z": { "type": "number" }
-            }
-        },
-        "dimensions": {
+        "extents": {
+            "description": "The outer dimensions of the labware.",
             "type": "object",
+            "required": ["total", "footprint"],
             "additionalProperties": false,
-            "description": "Outer dimensions of a labware",
-            "required": ["xDimension", "yDimension", "zDimension"],
             "properties": {
-                "yDimension": {
-                    "$ref": "#/definitions/positiveNumber"
+                "total": {
+                    "description": "The all-encompassing outer dimensions of the labware.",
+                    "$ref": "#/definitions/axisAlignedBoundingBox3D"
                 },
-                "zDimension": {
-                    "$ref": "#/definitions/positiveNumber"
-                },
-                "xDimension": {
-                    "$ref": "#/definitions/positiveNumber"
+                "footprint": {
+                    "description": "The outer dimensions of the labware where it meets the deck.",
+                    "$ref": "#/definitions/axisAlignedBoundingBox2D"
                 }
             }
         },
@@ -442,62 +635,7 @@
             "additionalProperties": false,
             "patternProperties": {
                 "[A-Z]+[0-9]+": {
-                    "type": "object",
-                    "additionalProperties": false,
-                    "required": ["depth", "shape", "totalLiquidVolume", "x", "y", "z"],
-                    "oneOf": [
-                        { "required": ["xDimension", "yDimension"] },
-                        { "required": ["diameter"] }
-                    ],
-                    "not": {
-                        "anyOf": [
-                            { "required": ["diameter", "xDimension"] },
-                            { "required": ["diameter", "yDimension"] }
-                        ]
-                    },
-                    "properties": {
-                        "depth": {
-                            "description": "The distance between the top and bottom of this well. If the labware is a tip rack, this will be ignored in favor of tipLength, but the values should match.",
-                            "$ref": "#/definitions/positiveNumber"
-                        },
-                        "x": {
-                            "description": "x location of center-bottom of well in reference to left-front-bottom of labware",
-                            "$ref": "#/definitions/positiveNumber"
-                        },
-                        "y": {
-                            "description": "y location of center-bottom of well in reference to left-front-bottom of labware",
-                            "$ref": "#/definitions/positiveNumber"
-                        },
-                        "z": {
-                            "description": "z location of center-bottom of well in reference to left-front-bottom of labware",
-                            "$ref": "#/definitions/positiveNumber"
-                        },
-                        "totalLiquidVolume": {
-                            "description": "Total well, tube, or tip volume in microliters",
-                            "$ref": "#/definitions/positiveNumber"
-                        },
-                        "xDimension": {
-                            "description": "x dimension of rectangular wells",
-                            "$ref": "#/definitions/positiveNumber"
-                        },
-                        "yDimension": {
-                            "description": "y dimension of rectangular wells",
-                            "$ref": "#/definitions/positiveNumber"
-                        },
-                        "diameter": {
-                            "description": "diameter of circular wells",
-                            "$ref": "#/definitions/positiveNumber"
-                        },
-                        "shape": {
-                            "description": "If 'rectangular', use xDimension and yDimension; if 'circular' use diameter",
-                            "type": "string",
-                            "enum": ["rectangular", "circular"]
-                        },
-                        "geometryDefinitionId": {
-                            "description": "string id of the well's corresponding innerWellGeometry",
-                            "type": ["string", "null"]
-                        }
-                    }
+                    "$ref": "#/definitions/well"
                 }
             }
         },
@@ -549,40 +687,49 @@
             "description": "Allowed behaviors and usage of a labware in a protocol.",
             "items": {
                 "type": "string",
-                "enum": ["labware", "adapter", "fixture", "maintenance", "lid"]
+                "enum": [
+                    "labware",
+                    "adapter",
+                    "fixture",
+                    "maintenance",
+                    "lid",
+                    "system"
+                ]
             }
         },
         "stackingOffsetWithLabware": {
             "type": "object",
             "description": "Supported labware that can be stacked upon, with overlap height between both labware.",
             "additionalProperties": {
-                "$ref": "#/definitions/coordinates"
+                "$ref": "#/definitions/vector3D"
             }
         },
         "stackingOffsetWithModule": {
             "type": "object",
             "description": "Supported module that can be stacked upon, with overlap height between labware and module.",
             "additionalProperties": {
-                "$ref": "#/definitions/coordinates"
+                "$ref": "#/definitions/vector3D"
             }
         },
         "gripperOffsets": {
             "type": "object",
-            "description": "Offsets to be added when calculating the coordinates a gripper should go to when picking up or dropping a labware on this labware.",
+            "description": "Offsets to add when picking up or dropping another labware stacked atop this one. Do not use this to adjust the position of the gripper paddles relative to this labware or the child labware; use `gripHeightFromLabwareBottom` on this definition or the child's definition for that.",
+            "additionalProperties": {
+                "$ref": "#/definitions/pickUpAndDropOffsets",
+                "description": "Properties here are named for, and matched based on, the deck slot that this labware is atop--or, if this labware is atop a module, the deck slot that that module is atop."
+            },
             "properties": {
                 "default": {
-                    "type": "object",
-                    "properties": {
-                        "pickUpOffset": {
-                            "$ref": "#/definitions/coordinates",
-                            "description": "Offset added to calculate pick-up coordinates of a labware placed on this labware."
-                        },
-                        "dropOffset": {
-                            "$ref": "#/definitions/coordinates",
-                            "description": "Offset added to calculate drop coordinates of a labware placed on this labware."
-                        }
-                    },
-                    "required": ["pickUpOffset", "dropOffset"]
+                    "$ref": "#/definitions/pickUpAndDropOffsets",
+                    "description": "The offsets to use if there's no slot-specific match in `additionalProperties`."
+                },
+                "lidOffsets": {
+                    "$ref": "#/definitions/pickUpAndDropOffsets",
+                    "description": "Additional offsets for gripping this labware, if this labware is a lid. Beware this property's placement: instead of affecting the labware stacked atop this labware, like the rest of the `gripperOffsets` properties, it affects this labware."
+                },
+                "lidDisposalOffsets": {
+                    "$ref": "#/definitions/pickUpAndDropOffsets",
+                    "description": "Additional offsets for gripping this labware, if this labware is a lid and it's being moved to a trash bin. Beware this property's placement: instead of affecting the labware stacked atop this labware, like the rest of the `gripperOffsets` properties, it affects this labware."
                 }
             }
         },
@@ -594,6 +741,17 @@
             "type": "number",
             "description": "Recommended Z-height, from labware bottom to the center of gripper pads, when gripping the labware."
         },
+        "stackLimit": {
+            "type": "number",
+            "description": "The limit representing the maximum stack size for a given labware. Defaults to 1 when unspecified indicating a single labware with no labware below it."
+        },
+        "compatibleParentLabware": {
+            "type": "array",
+            "description": "Array of parent Labware on which a labware may be loaded, primarily the labware which owns a lid.",
+            "items": {
+                "type": "string"
+            }
+        },
         "innerLabwareGeometry": {
             "type": ["object", "null"],
             "description": "A dictionary holding all unique inner well geometries in a labware.",