feat(shared-data): add in-schema versions to liquid class schema and definitions

api/src/opentrons/protocol_api/core/engine/protocol.py

@@ -1071,7 +1071,7 @@ def define_liquid(
             display_color=(liquid.displayColor.root if liquid.displayColor else None),
         )
 
-    def define_liquid_class(self, name: str) -> LiquidClass:
+    def define_liquid_class(self, name: str, version: int = 1) -> LiquidClass:
         """Define a liquid class for use in transfer functions."""
         try:
             # Check if we have already loaded this liquid class' definition
@@ -1081,7 +1081,7 @@ def define_liquid_class(self, name: str) -> LiquidClass:
                 # Fetching the liquid class data from file and parsing it
                 # is an expensive operation and should be avoided.
                 # Calling this often will degrade protocol execution performance.
-                liquid_class_def = liquid_classes.load_definition(name)
+                liquid_class_def = liquid_classes.load_definition(name, version=version)
                 self._defined_liquid_class_defs_by_name[name] = liquid_class_def
             except LiquidClassDefinitionDoesNotExist:
                 raise ValueError(f"Liquid class definition not found for '{name}'.")

api/tests/opentrons/conftest.py

@@ -798,6 +798,7 @@ def minimal_liquid_class_def1() -> LiquidClassSchemaV1:
         displayName="water 1",
         description="some water",
         schemaVersion=1,
+        version=1,
         namespace="test-fixture-1",
         byPipette=[],
     )
@@ -810,6 +811,7 @@ def minimal_liquid_class_def2() -> LiquidClassSchemaV1:
         displayName="water 2",
         description="some water",
         schemaVersion=1,
+        version=1,
         namespace="test-fixture-2",
         byPipette=[
             ByPipetteSetting(
@@ -896,6 +898,7 @@ def maximal_liquid_class_def() -> LiquidClassSchemaV1:
         displayName="Test Water",
         description="some water",
         schemaVersion=1,
+        version=1,
         namespace="opentrons",
         byPipette=[
             ByPipetteSetting(

api/tests/opentrons/protocol_api/core/engine/test_protocol_core.py

@@ -1876,15 +1876,15 @@ def test_define_liquid_class(
     expected_liquid_class = LiquidClass(
         _name="water1", _display_name="water 1", _by_pipette_setting={}
     )
-    decoy.when(liquid_classes.load_definition("water")).then_return(
+    decoy.when(liquid_classes.load_definition("water", version=123)).then_return(
         minimal_liquid_class_def1
     )
-    assert subject.define_liquid_class("water") == expected_liquid_class
+    assert subject.define_liquid_class("water", version=123) == expected_liquid_class
 
-    decoy.when(liquid_classes.load_definition("water")).then_return(
+    decoy.when(liquid_classes.load_definition("water", version=456)).then_return(
         minimal_liquid_class_def2
     )
-    assert subject.define_liquid_class("water") == expected_liquid_class
+    assert subject.define_liquid_class("water", version=456) == expected_liquid_class
 
 
 def test_get_labware_location_deck_slot(

shared-data/js/liquidClasses.ts

@@ -1,6 +1,6 @@
-import ethanol80V1Uncasted from '../liquid-class/definitions/1/ethanol_80.json'
-import glycerol50V1Uncasted from '../liquid-class/definitions/1/glycerol_50.json'
-import waterV1Uncasted from '../liquid-class/definitions/1/water.json'
+import ethanol80V1Uncasted from '../liquid-class/definitions/1/ethanol_80/1.json'
+import glycerol50V1Uncasted from '../liquid-class/definitions/1/glycerol_50/1.json'
+import waterV1Uncasted from '../liquid-class/definitions/1/water/1.json'
 
 import type { LiquidClass } from '.'
 

shared-data/liquid-class/definitions/1/ethanol_80.json → shared-data/liquid-class/definitions/1/ethanol_80/1.json

@@ -3,6 +3,7 @@
   "displayName": "Volatile",
   "description": "80% ethanol",
   "schemaVersion": 1,
+  "version": 1,
   "namespace": "opentrons",
   "byPipette": [
     {

shared-data/liquid-class/definitions/1/glycerol_50.json → shared-data/liquid-class/definitions/1/glycerol_50/1.json

@@ -3,6 +3,7 @@
   "displayName": "Viscous",
   "description": "50% glycerol",
   "schemaVersion": 1,
+  "version": 1,
   "namespace": "opentrons",
   "byPipette": [
     {

shared-data/liquid-class/definitions/1/water.json → shared-data/liquid-class/definitions/1/water/1.json

@@ -3,6 +3,7 @@
   "displayName": "Aqueous",
   "description": "Deionized water",
   "schemaVersion": 1,
+  "version": 1,
   "namespace": "opentrons",
   "byPipette": [
     {

shared-data/liquid-class/fixtures/1/fixture_glycerol50.json

@@ -3,6 +3,7 @@
   "displayName": "Viscous",
   "description": "50% glycerol",
   "schemaVersion": 1,
+  "version": 1,
   "namespace": "opentrons",
   "byPipette": [
     {

shared-data/liquid-class/schemas/1.json

@@ -443,6 +443,11 @@
       "type": "number",
       "enum": [1]
     },
+    "version": {
+      "description": "Version of the liquid class definition itself (eg water v1/v2/v3). An incrementing integer",
+      "type": "integer",
+      "minimum": 1
+    },
     "namespace": {
       "$ref": "#/definitions/safeString"
     },
@@ -492,6 +497,7 @@
     "displayName",
     "description",
     "schemaVersion",
+    "version",
     "namespace",
     "byPipette"
   ],

shared-data/python/opentrons_shared_data/liquid_classes/__init__.py

@@ -4,23 +4,27 @@
 from .liquid_class_definition import LiquidClassSchemaV1
 
 
-DEFAULT_VERSION = 1
+DEFAULT_SCHEMA_VERSION = 1
 
 
 class LiquidClassDefinitionDoesNotExist(Exception):
     """Specified liquid class definition does not exist."""
 
 
-def load_definition(name: str, version: int = DEFAULT_VERSION) -> LiquidClassSchemaV1:
+def load_definition(
+    name: str, version: int, schema_version: int = DEFAULT_SCHEMA_VERSION
+) -> LiquidClassSchemaV1:
     """Load the specified liquid class' definition as a LiquidClassSchemaV1 object.
 
     Note: this is an expensive operation and should be called sparingly.
     """
     try:
         return LiquidClassSchemaV1.model_validate_json(
-            load_shared_data(f"liquid-class/definitions/{version}/{name}.json")
+            load_shared_data(
+                f"liquid-class/definitions/{schema_version}/{name}/{version}.json"
+            )
         )
     except FileNotFoundError:
         raise LiquidClassDefinitionDoesNotExist(
-            f"No definition found for liquid class '{name}'"
+            f"No definition found for liquid class '{name}' version {version}"
         )

shared-data/python/opentrons_shared_data/liquid_classes/liquid_class_definition.py

@@ -393,6 +393,9 @@ class LiquidClassSchemaV1(BaseModel):
     schemaVersion: Literal[1] = Field(
         ..., description="Which schema version a liquid class is using"
     )
+    version: int = Field(
+        ..., description="Version of the liquid class within the schema"
+    )
     namespace: str = Field(...)
     byPipette: Sequence[ByPipetteSetting] = Field(
         ...,

shared-data/python/tests/liquid_classes/test_load.py

@@ -14,7 +14,7 @@
 
 
 def test_load_liquid_class_schema_v1() -> None:
-    fixture_data = load_shared_data("liquid-class/definitions/1/water.json")
+    fixture_data = load_shared_data("liquid-class/definitions/1/water/1.json")
     liquid_class_model = LiquidClassSchemaV1.model_validate_json(fixture_data)
     liquid_class_def_from_model = json.loads(
         liquid_class_model.model_dump_json(exclude_unset=True)
@@ -24,7 +24,7 @@ def test_load_liquid_class_schema_v1() -> None:
 
 
 def test_load_definition() -> None:
-    water_definition = load_definition(name="water", version=1)
+    water_definition = load_definition(name="water", version=1, schema_version=1)
     assert type(water_definition) is LiquidClassSchemaV1
     assert water_definition.byPipette[0].pipetteModel == "flex_1channel_50"
     assert water_definition.byPipette[0].byTipType[0].aspirate.submerge == Submerge(

shared-data/python/tests/liquid_classes/test_validations.py

@@ -18,15 +18,15 @@ def _get_all_liquid_classes() -> List[str]:
 @pytest.mark.parametrize("liquid_class_name", list(_get_all_liquid_classes()))
 def test_validate_unique_pipette_keys(liquid_class_name: str) -> None:
     """A liquid class definition should contain only one set of properties per pipette model."""
-    definition_dict = load_definition(liquid_class_name, version=1)
+    definition_dict = load_definition(liquid_class_name, version=1, schema_version=1)
     pipette_models = [prop.pipetteModel for prop in definition_dict.byPipette]
     assert len(pipette_models) == len(set(pipette_models))
 
 
 @pytest.mark.parametrize("liquid_class_name", list(_get_all_liquid_classes()))
 def test_validate_unique_tip_keys(liquid_class_name: str) -> None:
     """A liquid class definition should contain only one set of properties per tip type."""
-    definition_dict = load_definition(liquid_class_name, version=1)
+    definition_dict = load_definition(liquid_class_name, version=1, schema_version=1)
 
     for by_pip_prop in definition_dict.byPipette:
         tipracks = [tip_prop.tiprack for tip_prop in by_pip_prop.byTipType]