[Engine] JSON Schema validation for file-read steps

[ameet]

Problem

Flows that read JSON config files (file-read with parseJson: true) have no way to validate the structure of what they read. Config files are load-bearing — if a field is missing or has the wrong type, the flow fails at runtime with an unhelpful error deep in a downstream code step.

Example

A flow reads a scoring rubric config:

{
  "id": "loadRubric",
  "type": "file-read",
  "fileRead": {
    "path": ".config/scoring-rubric.json",
    "parseJson": true
  }
}

The config file must have exactly 15 sections, each with number, name, and type fields, plus a sourcePriority map covering every section name. If any of this is wrong, the flow silently produces garbage output.

Today, teams build external validation scripts that manually check:

• Required fields exist
• Field types are correct
• Enum values are from an allowed set
• Array lengths match expectations
• Cross-references are consistent (e.g., every section name appears in the priority map)

Proposal

Allow file-read steps to declare a JSON Schema:

{
  "id": "loadRubric",
  "type": "file-read",
  "fileRead": {
    "path": ".config/scoring-rubric.json",
    "parseJson": true,
    "schema": ".config/schemas/scoring-rubric.schema.json"
  }
}

Or inline:

{
  "id": "loadRubric",
  "type": "file-read",
  "fileRead": {
    "path": ".config/scoring-rubric.json",
    "parseJson": true,
    "schema": {
      "type": "object",
      "required": ["canonicalSections", "sourcePriority"],
      "properties": {
        "canonicalSections": {
          "type": "array",
          "minItems": 15,
          "maxItems": 15
        }
      }
    }
  }
}

Benefits

• Fail fast with clear error: "loadRubric: config validation failed: canonicalSections has 14 items, expected 15"
• one flow validate can check schemas without executing the flow
• Self-documenting: the schema IS the contract for the config file
• Reusable across flows that read the same config