docs(api,robot-server): Document errors list as having no more than 1…

… element (#13191)

api/src/opentrons/cli/analyze.py

@@ -140,7 +140,10 @@ class PythonConfig(BaseModel):
 
 
 class AnalyzeResults(BaseModel):
-    """Results of a protocol analysis."""
+    """Results of a protocol analysis.
+
+    See robot-server's analysis models for field documentation.
+    """
 
     createdAt: datetime
     files: List[ProtocolFile]

api/src/opentrons/protocol_engine/state/state_summary.py

@@ -18,6 +18,8 @@ class StateSummary(BaseModel):
     """Data from a protocol run."""
 
     status: EngineStatus
+    # errors is a list for historical reasons. (This model needs to stay compatible with
+    # robot-server's database.) It shouldn't have more than 1 element.
     errors: List[ErrorOccurrence]
     labware: List[LoadedLabware]
     pipettes: List[LoadedPipette]

robot-server/robot_server/maintenance_runs/maintenance_run_models.py

@@ -76,7 +76,11 @@ class MaintenanceRun(ResourceModel):
     )
     errors: List[ErrorOccurrence] = Field(
         ...,
-        description="Any errors that have occurred during the run.",
+        description=(
+            "The run's fatal error, if there was one."
+            " For historical reasons, this is an array,"
+            " but it won't have more than one element."
+        ),
     )
     pipettes: List[LoadedPipette] = Field(
         ...,

robot-server/robot_server/protocols/analysis_models.py

@@ -108,7 +108,11 @@ class CompletedAnalysis(BaseModel):
     )
     errors: List[ErrorOccurrence] = Field(
         ...,
-        description="Any errors the protocol run produced",
+        description=(
+            "The protocol's fatal error, if there was one."
+            " For historical reasons, this is an array,"
+            " but it won't have more than one element."
+        ),
     )
     liquids: List[Liquid] = Field(
         default_factory=list,

robot-server/robot_server/runs/run_models.py

@@ -77,7 +77,11 @@ class Run(ResourceModel):
     )
     errors: List[ErrorOccurrence] = Field(
         ...,
-        description="Any errors that have occurred during the run.",
+        description=(
+            "The run's fatal error, if there was one."
+            " For historical reasons, this is an array,"
+            " but it won't have more than one element."
+        ),
     )
     pipettes: List[LoadedPipette] = Field(
         ...,