schema v2 for command annotations

Author: jbleon95

api/src/opentrons/protocol_runner/json_translator.py

@@ -304,11 +304,13 @@ def translate_command_annotations(
         """Translate command annotations in json protocol schema v8."""
         if isinstance(protocol, (ProtocolSchemaV6, ProtocolSchemaV7)):
             return []
-        else:
+        elif protocol.commandAnnotationSchemaId == "opentronsCommandAnnotationSchemaV1":
             command_annotations: List[CommandAnnotation] = [
                 CommandAnnotationAdapter.validate_python(
                     command_annotation.model_dump(),
                 )
                 for command_annotation in protocol.commandAnnotations
             ]
             return command_annotations
+        else:
+            return []

shared-data/commandAnnotation/schemas/2.json

@@ -0,0 +1,104 @@
+{
+  "$id": "opentronsCommandAnnotationSchemaV2#",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$defs": {
+    "baseAnnotation": {
+      "description": "Things all annotations have",
+      "type": "object",
+      "required": ["annotationType", "annotationID"],
+      "properties": {
+        "annotationID": {
+          "description": "A unique identifier for a command annotation.",
+          "type": "string"
+        },
+        "annotationType": {
+          "description": "The type of annotation (for machine parsing)",
+          "type": "string"
+        },
+        "parentAnnotation": {
+          "description": "The parent annotation of this annotation, if any.",
+          "type": "string"
+        }
+      }
+    },
+    "secondOrderCommand": {
+      "description": "Annotates a group of atomic commands which were the direct result of a second order command (e.g. transfer, consolidate, mix)",
+      "allOf": [{ "$ref": "#/$defs/baseAnnotation" }],
+      "type": "object",
+      "required": [
+        "annotationType",
+        "commandKeys",
+        "params",
+        "machineReadableName"
+      ],
+      "properties": {
+        "annotationType": {
+          "type": "string",
+          "enum": ["secondOrderCommand"]
+        },
+        "params": {
+          "description": "key value pairs of the parameters that were passed to the second order command that this annotates",
+          "type": "object"
+        },
+        "machineReadableName": {
+          "description": "The name of the second order command in the form that the generating software refers to it. (e.g. 'transfer', 'thermocyclerStep')",
+          "type": "string"
+        },
+        "userSpecifiedName": {
+          "description": "The optional user-specified name of the second order command",
+          "type": "string"
+        },
+        "userSpecifiedDescription": {
+          "description": "The optional user-specified description of the second order command",
+          "type": "string"
+        }
+      }
+    },
+    "userCommand": {
+      "description": "A user generated command annotation as opposed to one generated automatically.",
+      "allOf": [{ "$ref": "#/$defs/baseAnnotation" }],
+      "type": "object",
+      "required": [
+        "annotationType",
+        "annotationID",
+        "params",
+        "userSpecifiedName"
+      ],
+      "properties": {
+        "annotationType": {
+          "type": "string",
+          "enum": ["userCommand"]
+        },
+        "params": {
+          "description": "key value pairs of the parameters that were passed to the second order command that this annotates",
+          "type": "object"
+        },
+        "userSpecifiedName": {
+          "description": "The optional user-specified name of the second order command",
+          "type": "string"
+        },
+        "userSpecifiedDescription": {
+          "description": "The optional user-specified description of the second order command",
+          "type": "string"
+        }
+      }
+    },
+    "custom": {
+      "description": "Annotates a group of atomic commands in some manner that Opentrons software does not anticipate or originate",
+      "allOf": [{ "$ref": "#/$defs/baseAnnotation" }],
+      "type": "object",
+      "required": ["annotationType", "commandKeys"],
+      "properties": {
+        "annotationType": {
+          "type": "string",
+          "enum": ["custom"]
+        }
+      },
+      "additionalProperties": true
+    }
+  },
+  "oneOf": [
+    { "$ref": "#/$defs/secondOrderCommand" },
+    { "$ref": "#/$defs/custom" }
+  ]
+}

shared-data/python/opentrons_shared_data/protocol/models/protocol_schema_v8.py

@@ -1,5 +1,5 @@
 from enum import Enum
-from typing import Any, List, Optional, Dict
+from typing import Any, List, Optional, Dict, Union
 from typing_extensions import Literal
 
 from pydantic import BaseModel, Field, ConfigDict
@@ -50,7 +50,10 @@ class ProtocolSchemaV8(BaseModel):
     labwareDefinitions: Dict[str, LabwareDefinition]
     commandSchemaId: CommandSchemaId
     commands: List[Command]
-    commandAnnotationSchemaId: Literal["opentronsCommandAnnotationSchemaV1"]
+    commandAnnotationSchemaId: Union[
+        Literal["opentronsCommandAnnotationSchemaV1"],
+        Literal["opentronsCommandAnnotationSchemaV2"],
+    ]
     commandAnnotations: List[CommandAnnotation]
     designerApplication: Optional[DesignerApplication] = None
     model_config = ConfigDict(populate_by_name=True)