calminer-docs/specifications/scenario_validation.md

Scenario Validation Rules

Last updated: 2025-11-09

This document captures the validation rules that must run before comparing two or more scenarios within the CalMiner application. The rules are enforced inside the scenario service layer and surfaced through the API and HTML workflows.

Comparison Preconditions

All scenarios included in a comparison request must satisfy the following preconditions:

Rule	Description	Error Code	Client Message
Same project	Every scenario must belong to the same project identifier.	SCENARIO_PROJECT_MISMATCH	"Selected scenarios do not belong to the same project."
Active status	Only scenarios in draft or active status may be compared. Archived scenarios are rejected.	SCENARIO_STATUS_INVALID	"Archived scenarios cannot be compared."
Shared currency	Scenarios must share the same currency value when provided.	SCENARIO_CURRENCY_MISMATCH	"Scenarios use different currencies and cannot be compared."
Timeline coherence	When both scenarios provide date ranges, they must overlap or touch (inclusive). Non-overlapping ranges raise a conflict.	SCENARIO_TIMELINE_DISJOINT	"Scenario timelines do not overlap; adjust the comparison window."
Primary resource alignment	Scenarios must declare the same primary_resource (if set). When one is unset, the non-null value is applied to both. If both are set but differ, the comparison fails.	SCENARIO_RESOURCE_MISMATCH	"Scenarios target different primary resources and cannot be compared."

Error Response Contract

When a validation rule fails, the service layer raises a ScenarioValidationError (to be implemented) containing:

• a machine-readable code from the table above,
• a human-readable message designed for UI display,
• a list of related scenario_ids that triggered the rule (if available).

The API adapts the error into an HTTP 422 Unprocessable Entity payload:

{
  "detail": {
    "code": "SCENARIO_PROJECT_MISMATCH",
    "message": "Selected scenarios do not belong to the same project.",
    "scenario_ids": [12, 19]
  }
}

HTML form flows display the message as a banner and set the HTTP status to 400.

Future Considerations

• Expand rules to cover incompatible simulation parameter configurations once parameter taxonomy stabilises.
• Provide localized error message variants when the internationalization framework is introduced.