change is_control to str in QueryModel & add basic validation

app/api/models.py

@@ -4,7 +4,8 @@
 from typing import Optional, Union
 
 from fastapi import Query
-from pydantic import BaseModel, Field
+from fastapi.exceptions import HTTPException
+from pydantic import BaseModel, Field, validator
 
 CONTROLLED_TERM_REGEX = r"^[a-zA-Z]+[:]\S+$"
 
@@ -16,7 +17,7 @@ class QueryModel(BaseModel):
     max_age: float = None
     sex: str = None
     diagnosis: str = None
-    is_control: bool = None
+    is_control: str = None
     min_num_imaging_sessions: int = None
     min_num_phenotypic_sessions: int = None
     assessment: str = None
@@ -27,6 +28,20 @@ class QueryModel(BaseModel):
     # syntax from https://github.com/tiangolo/fastapi/issues/4445#issuecomment-1117632409
     node_url: list[str] | None = Field(Query(default=[]))
 
+    @validator("is_control")
+    def check_allowed_iscontrol_values(cls, v):
+        """Raise a validation error if the value of 'is_control' is not 'true' (case-insensitive) or None."""
+        if v is not None:
+            # Ensure that the allowed value is case-insensitive
+            if v.lower() != "true":
+                raise HTTPException(
+                    status_code=422,
+                    detail="'is_control' must be either set to 'true' or omitted from the query",
+                )
+            # Keep it a str because that's what the n-API expects
+            return v
+        return None
+
 
 class CohortQueryResponse(BaseModel):
     """Data model for query results for one matching dataset (i.e., a cohort)."""