determination.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://formspec.org/schemas/determination/1.0",
  "title": "Formspec Determination Record",
  "description": "A Formspec Determination Record — the structured output artifact produced by evaluating a Screener Document against respondent inputs. A Determination Record captures the complete evaluation outcome: which routes matched, which were eliminated and why, computed scores, the respondent's input values with answer states, and evaluation metadata. The record references the specific screener version that produced it via the (screener.url, screener.version) tuple. Determination Records are immutable once produced; status may transition from 'completed' to 'expired' when the screener's resultValidity duration elapses, but the evaluation data itself is never modified. Status 'unavailable' indicates the screener was outside its availability window and no evaluation was performed.",
  "type": "object",
  "required": [
    "$formspecDetermination",
    "screener",
    "timestamp",
    "evaluationVersion",
    "status",
    "overrides",
    "phases",
    "inputs"
  ],
  "additionalProperties": false,
  "properties": {
    "$formspecDetermination": {
      "type": "string",
      "const": "1.0",
      "description": "Determination Record specification version. MUST be '1.0'.",
      "examples": ["1.0"],
      "x-lm": {
        "critical": true,
        "intent": "Version pin for Determination Record compatibility. Processors MUST reject records with an unrecognized version."
      }
    },
    "screener": {
      "type": "object",
      "description": "Reference to the Screener Document that produced this record. The (url, version) tuple uniquely identifies the screener revision whose evaluation logic was applied.",
      "required": ["url", "version"],
      "properties": {
        "url": {
          "type": "string",
          "format": "uri",
          "description": "Canonical URI of the screener that produced this record.",
          "examples": [
            "urn:example:grants-eligibility-screener",
            "https://agency.gov/screeners/benefit-eligibility"
          ]
        },
        "version": {
          "type": "string",
          "description": "Semantic version of the screener that produced this record.",
          "examples": ["1.0.0", "2.1.0"]
        }
      },
      "additionalProperties": false,
      "x-lm": {
        "critical": true,
        "intent": "Provenance link to the exact screener revision. Enables auditing and reproducibility."
      }
    },
    "timestamp": {
      "type": "string",
      "format": "date-time",
      "description": "ISO 8601 date-time when the evaluation completed.",
      "examples": ["2026-03-31T14:30:00Z"]
    },
    "evaluationVersion": {
      "type": "string",
      "description": "The version of the Screener Document's evaluation logic that was applied. Reflects the evaluationBinding policy: if 'submission', this is the screener version at session start; if 'completion', the version at evaluation time.",
      "examples": ["1.0.0"]
    },
    "status": {
      "type": "string",
      "enum": ["completed", "partial", "expired", "unavailable"],
      "description": "'completed': all items answered and evaluation finished. 'partial': not all items answered; evaluation ran on available data. 'expired': result validity duration exceeded post-evaluation. 'unavailable': screener was outside its availability window, no evaluation performed.",
      "examples": ["completed"],
      "x-lm": {
        "critical": true,
        "intent": "Evaluation outcome status. Consuming applications MUST check status before acting on matched routes."
      }
    },
    "overrides": {
      "type": "object",
      "description": "Results of override route evaluation. Override routes are hoisted out of their declaring phase and evaluated before all phases.",
      "required": ["matched", "halted"],
      "properties": {
        "matched": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/RouteResult"
          },
          "description": "Override routes that fired. Empty array when no overrides matched."
        },
        "halted": {
          "type": "boolean",
          "description": "true if a terminal override halted the pipeline. When true, the phases array is empty because no phases were evaluated."
        }
      },
      "additionalProperties": false
    },
    "phases": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/PhaseResult"
      },
      "description": "Per-phase evaluation results in declaration order. Empty array if overrides halted the pipeline."
    },
    "inputs": {
      "type": "object",
      "additionalProperties": {
        "$ref": "#/$defs/InputEntry"
      },
      "description": "Map of item path to { value, state } for every screener item. Keys use Formspec path syntax including indexed repeat paths (e.g., 'group[0].field').",
      "x-lm": {
        "critical": true,
        "intent": "Complete snapshot of respondent inputs at evaluation time. Enables auditing and replay without re-collecting data."
      }
    },
    "validity": {
      "type": "object",
      "description": "Expiration metadata derived from the screener's resultValidity duration. Omitted when the screener does not declare resultValidity.",
      "properties": {
        "validUntil": {
          "type": "string",
          "format": "date-time",
          "description": "When this Determination Record expires. Computed as timestamp + resultValidity.",
          "examples": ["2026-04-14T14:30:00Z"]
        },
        "resultValidity": {
          "type": "string",
          "description": "The original ISO 8601 duration from the Screener Document.",
          "examples": ["P14D", "P90D"]
        }
      },
      "additionalProperties": false
    },
    "extensions": {
      "type": "object",
      "propertyNames": {
        "pattern": "^x-"
      },
      "description": "Extension data on the Determination Record. Uses the same x-prefixed extension mechanism as other Formspec documents."
    }
  },
  "$defs": {
    "PhaseResult": {
      "type": "object",
      "description": "Evaluation result for a single phase in the pipeline. Captures the phase's status, strategy, matched and eliminated routes, and any phase-level warnings.",
      "required": ["id", "status", "strategy", "matched", "eliminated"],
      "properties": {
        "id": {
          "type": "string",
          "description": "Phase identifier, matching the 'id' of the corresponding Phase in the Screener Document."
        },
        "status": {
          "type": "string",
          "enum": ["evaluated", "skipped", "unsupported-strategy"],
          "description": "'evaluated': phase ran normally. 'skipped': phase's activeWhen expression evaluated to false. 'unsupported-strategy': processor does not support this phase's strategy (Core conformance only requires 'first-match')."
        },
        "strategy": {
          "type": "string",
          "description": "The evaluation strategy that was used (or would have been used if skipped/unsupported)."
        },
        "matched": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/RouteResult"
          },
          "description": "Routes that matched in this phase."
        },
        "eliminated": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/RouteResult"
          },
          "description": "Routes that did not match in this phase, with reasons for elimination."
        },
        "warnings": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "default": [],
          "description": "Phase-level warnings emitted during evaluation (e.g., 'below-minimum' when fan-out matches fewer than config.minMatches).",
          "examples": [["below-minimum"]]
        }
      },
      "additionalProperties": false
    },
    "RouteResult": {
      "type": "object",
      "description": "A single route's evaluation outcome within a phase or override block. Present in both 'matched' and 'eliminated' arrays. Eliminated results include a reason explaining why the route did not match.",
      "required": ["target"],
      "properties": {
        "target": {
          "type": "string",
          "description": "The route's target URI. Matches the 'target' property of the corresponding Route in the Screener Document."
        },
        "label": {
          "type": "string",
          "description": "The route's human-readable label, copied from the Screener Document."
        },
        "message": {
          "type": "string",
          "description": "The route's respondent-facing message. Preserved so consuming applications can display it without re-reading the Screener Document. If the Screener Route contained {{expression}} interpolation sequences, the message is the post-interpolation result."
        },
        "score": {
          "type": "number",
          "description": "The computed score for score-threshold routes. Present only when the route was evaluated under a 'score-threshold' strategy."
        },
        "reason": {
          "type": "string",
          "description": "Why the route was eliminated: 'condition-false', 'below-threshold', 'max-exceeded', 'null-score'. Present only in the 'eliminated' array. 'null-score' indicates the score expression evaluated to null (e.g., due to non-relevant items).",
          "examples": ["condition-false", "below-threshold", "null-score"]
        },
        "metadata": {
          "type": "object",
          "description": "The route's arbitrary metadata, copied from the Screener Document without interpretation.",
          "additionalProperties": true
        }
      },
      "additionalProperties": false
    },
    "InputEntry": {
      "type": "object",
      "description": "A single screener item's captured value and answer state at evaluation time. The key in the inputs map is the item's Formspec path, which may include indexed repeat paths (e.g., 'group[0].field') for items inside repeatable groups.",
      "required": ["state"],
      "properties": {
        "value": {
          "description": "The item's value at evaluation time. May be any JSON type (string, number, boolean, array, object, null). null when state is 'declined' or 'not-presented'."
        },
        "state": {
          "type": "string",
          "enum": ["answered", "declined", "not-presented"],
          "description": "'answered': respondent provided a value. 'declined': item was presented but respondent explicitly declined to answer. 'not-presented': item was not shown to the respondent (e.g., relevance was false)."
        }
      },
      "additionalProperties": false
    }
  }
}