Opentrons Custom Labware JSON Coordinate & ANSI/SLAS Datum Reference
When a pipette tip crashes 3 mm into a custom vial wall or stops 8 mm short of the meniscus, the root cause is almost always a coordinate-datum mismatch between CAD software and Opentrons’s Schema v2 labware definition. This reference documents the exact geometric rules used on every Datum Labware fixture.
1. The Deck Slot Origin (0, 0, 0) Is Front-Left-Bottom
Most mechanical CAD assemblies place (0, 0) at the geometric center of the microplate footprint or at well A1 (back-left). Opentrons instead anchors every deck slot at the front-left-bottom corner of the ANSI/SLAS 1-2004 footprint (127.76 × 85.48 mm):
- +X axis (0 → 127.76 mm): Left to right across the front of the robot.
- +Y axis (0 → 85.48 mm): Front to back. Well
A1sits near the back-left corner, soA1always has a smallxvalue (typically 14–22 mm) and a largeyvalue (typically 60–75 mm). - +Z axis (0 → zDimension): Deck floor upward.
2. The Critical Z Equation: well.z + well.depth = Seated Tube Top
In Opentrons Schema v2, wells["A1"].z is not the top of the tube and not the bottom of the rack bore. It is the vertical distance from the deck floor (Z = 0) to the interior bottom surface of the tube where the pipette tip touches at well.bottom(z=0):
floor_z = height of solid rack material beneath the tube base (e.g. 4.50 mm)
tube_bottom_wall = glass or polypropylene wall thickness at the base of the vial (e.g. 1.20 mm)
tube_height = overall uncapped height of the vial (e.g. 32.00 mm)
well.z = floor_z + tube_bottom_wall # 5.70 mm
seated_top_z = floor_z + tube_height # 36.50 mm (= dimensions.zDimension)
well.depth = seated_top_z - well.z # 30.80 mmIf you measure bore depth instead of seated interior tube depth, well.top() will sit inside the vial neck or above the rim, throwing off blow-out, touch-tip, and liquid-level tracking.
3. Five Validation Traps That Cause Opentrons App Import Errors
| JSON Field | Common Mistake | Required Schema v2 Rule |
|---|---|---|
| totalLiquidVolume | Entering 2.0 for a 2 mL vial because displayVolumeUnits is "mL". | Always specify volume in microliters (µL) (2000 for 2 mL, 20000 for 20 mL). |
| namespace | Inventing an uppercase or hyphenated namespace string. | Use "custom_beta" so protocol.load_labware(load_name, slot) resolves automatically without extra arguments. |
| ordering | Listing wells row-by-row (A1, A2, A3...). | Must be an array of column arrays ordered left-to-right, each listed back-to-front ([["A1","B1","C1","D1"], ["A2",...]]). |
| parameters | Adding undocumented keys such as manual gripForce in Schema v2. | Keep strictly to format, isTiprack, isMagneticModuleCompatible, and lowercase_underscore loadName. |
| groups | Trying to model mixed 20 mL + 2 mL racks in the web Labware Creator. | Author multiple entries inside groups[], each with its own wells list and wellBottomShape ("flat", "u", or "v"). |
4. Designing for 8-Channel Pipettes on Non-Standard Vials
Opentrons 8-channel pipettes have fixed nozzle spacing at 9.00 mm center-to-center along the Y axis. When a vial’s outer diameter exceeds 8.5 mm (such as 11.6 mm HPLC vials, 13 mm Vacutainers, or 15 mm 1-dram vials), place rows on an exact 18.00 mm Y pitch (2 × 9.00 mm). That allows 4-tip alternate-nozzle pickup or 2-step column transfers while maintaining full structural wall thickness between bores.
Need a custom rack or verified .json built to these exact rules? Open the Live Custom Configurator → or inspect our 8 pre-engineered Opentrons tube racks →