Merge pull request #1497 from PolicyEngine/codex/validate-household-variables

Validate household variables and publish OpenAPI spec

Author: anth-volk

changelog.d/1496.fixed

@@ -0,0 +1,5 @@
+Validate household calculate payload variables before simulation, returning
+HTTP 400 with structured `errors` for variables not available in the API's
+PolicyEngine model version while preserving allowlisted deprecated-variable
+warnings. Also expose the OpenAPI specification and document calculate request
+and response schemas.

policyengine_household_api/api.py

@@ -3,13 +3,19 @@
 """
 
 # Python imports
+from functools import lru_cache
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as package_version
 import os
+from pathlib import Path
+import tomllib
 
 # External imports
 from flask_cors import CORS
 import flask
 from flask_limiter import Limiter
 from flask_limiter.util import get_remote_address
+import yaml
 from policyengine_household_api.data.analytics_setup import (
     initialize_analytics_db_if_enabled,
 )
@@ -34,6 +40,9 @@
 print("Initialising API...")
 
 app = application = flask.Flask(__name__)
+OPENAPI_SPEC_PATH = Path(__file__).with_name("openapi_spec.yaml")
+PACKAGE_NAME = "policyengine-household-api"
+PYPROJECT_PATH = Path(__file__).resolve().parents[1] / "pyproject.toml"
 
 # Reject absurdly large request bodies before any view runs. 10 MiB is
 # well above the largest legitimate household payload we have seen
@@ -89,6 +98,28 @@ def readiness_check():
     )
 
 
+@app.route("/specification", methods=["GET"])
+def specification():
+    spec = load_openapi_spec()
+    return flask.jsonify(spec)
+
+
+def load_openapi_spec() -> dict:
+    with OPENAPI_SPEC_PATH.open() as spec_file:
+        spec = yaml.safe_load(spec_file)
+    spec.setdefault("info", {})["version"] = get_api_version()
+    return spec
+
+
+@lru_cache
+def get_api_version() -> str:
+    try:
+        return package_version(PACKAGE_NAME)
+    except PackageNotFoundError:
+        with PYPROJECT_PATH.open("rb") as pyproject_file:
+            return tomllib.load(pyproject_file)["project"]["version"]
+
+
 # Note: `/calculate_demo` is intentionally public (documented in
 # config/README.md). It is guarded by a conservative rate limit rather
 # than JWT authentication.

policyengine_household_api/endpoints/home.py

@@ -12,6 +12,9 @@ def get_home() -> Response:
         "result": {
             "docs_url": "https://www.policyengine.org/us/api",
             "container_image": "ghcr.io/policyengine/policyengine-household-api",
+            "openapi_spec_url": (
+                "https://household.api.policyengine.org/specification"
+            ),
             "hosted_calculate_url_template": (
                 "https://household.api.policyengine.org/{country_id}/calculate"
             ),

policyengine_household_api/endpoints/household.py

@@ -17,6 +17,9 @@
 from policyengine_household_api.utils.deprecated_inputs import (
     drop_deprecated_inputs,
 )
+from policyengine_household_api.utils.variable_validation import (
+    validate_household_variables,
+)
 from policyengine_household_api.utils.validate_country import validate_country
 
 
@@ -127,15 +130,44 @@ def get_calculate(country_id: str, add_missing: bool = False) -> Response:
 
     country = COUNTRIES.get(country_id)
 
-    # Strip deprecated inputs before validation so partners who still pass
-    # removed/renamed variables get a warning + working response instead
-    # of a `VariableNotFoundError` HTTP 500.
-    deprecation_warnings = drop_deprecated_inputs(household_json)
-
     # Validate inbound payload shape before reaching the compute layer.
     try:
         _validate_household_payload(country_id, household_json)
         _validate_axes(household_json)
+    except ValueError as e:
+        return Response(
+            json.dumps({"status": "error", "message": str(e)}),
+            status=400,
+            mimetype="application/json",
+        )
+
+    variable_errors = validate_household_variables(
+        household=household_json,
+        system=country.tax_benefit_system,
+        model_version=country.policyengine_bundle["model_version"],
+    )
+    if variable_errors:
+        return Response(
+            json.dumps(
+                {
+                    "status": "error",
+                    "message": "Invalid household variables.",
+                    "errors": [error.message for error in variable_errors],
+                }
+            ),
+            status=400,
+            mimetype="application/json",
+        )
+
+    # Strip deprecated inputs from a copy before period validation so
+    # partners who still pass removed/renamed variables get a warning +
+    # working response instead of a `VariableNotFoundError` HTTP 500.
+    deprecated_inputs = drop_deprecated_inputs(household_json)
+    household_json = deprecated_inputs.household
+    deprecation_warnings = deprecated_inputs.warnings
+
+    # Validate inbound period data before reaching the compute layer.
+    try:
         validate_period_keys(household_json, country.tax_benefit_system)
         validate_period_budgets(household_json, country.tax_benefit_system)
     except ValueError as e: