# V-5a — `Test-Json -SchemaFile` failure behaviour (local PowerShell)

**Status**: CLOSED
**Date**: 2026-08-20
**Environment**: PowerShell 7.6.5, Windows 11, local workstation (Stage A1 — offline, no tenant)
**Task**: T061
**Pinned by**: [tests/Configuration/TestJsonBehaviour.Tests.ps1](../../../tests/Configuration/TestJsonBehaviour.Tests.ps1)

## Question

OTD-005 selected `Test-Json -SchemaFile` for layer 2 validation. The documented risk was that
`Test-Json` reports schema failure inconsistently across PowerShell versions — returning `$false`,
writing a non-terminating error, or throwing. Layer 2 cannot be written until the actual behaviour
on the target build is observed rather than assumed.

## Observed behaviour

| Scenario | Return value | Error stream | Terminating? |
| --- | --- | --- | --- |
| Valid document | `$true` | empty | no |
| Type mismatch (`"a": 123` against `"type": "string"`) | `$false` | 1 error: `The JSON is not valid with the schema: Value is "integer" but should be "string" at '/a'` | no |
| Missing required property | `$false` | 1 error: `The JSON is not valid with the schema: Required properties ["a"] are not present at ''` | no |
| **Schema file itself unparseable** | **`$true`** | 1 error: `Cannot parse the JSON schema.` | no |

Exception type on the error record is `System.Exception` in every failing case — there is no
distinct exception type to branch on, so the wrapper must branch on the message text or, better, on
error presence alone.

## Findings that shape the implementation

1. **Non-terminating, not throwing.** With the default `$ErrorActionPreference = 'Continue'` the
   cmdlet writes to the error stream and execution continues, returning `$false`. It does not throw.
   `-ErrorAction SilentlyContinue -ErrorVariable` is therefore sufficient to capture failures, as
   the editor contract requires.

2. **An unparseable schema returns `$true`.** This is the load-bearing observation. A wrapper that
   trusted the return value alone would report a configuration as schema-valid when the schema never
   ran. Layer 2 MUST treat "error variable is non-empty" as failure regardless of the return value,
   and MUST distinguish the `Cannot parse the JSON schema.` message so it can surface exit code 4
   (schema file not found or itself invalid) rather than exit code 1 (configuration invalid).

3. **One error per violating location, but not exhaustive.** Two independent property violations
   yield two error records, each with its own JSON pointer. Deeper or nested subschema failures may
   still be reported as a single error at the outermost failing location. The wrapper therefore
   emits one finding per collected error rather than assuming a single one, and the author may still
   need more than one validation pass to see everything. That residual limitation is documented
   rather than worked around — full violation reporting would require replacing `Test-Json` with a
   third-party validator, which OTD-005 rejected.

## Consequences recorded elsewhere

- Layer 2 implementation: [src/Configuration/Test-PersonaConfiguration.ps1](../../../src/Configuration/Test-PersonaConfiguration.ps1)
- Regression pin: `tests/Configuration/TestJsonBehaviour.Tests.ps1` fails if a future PowerShell
  build changes any row of the table above.
- **V-5b remains open**: this observation is for PowerShell 7.6.5 only. The Azure Automation runtime
  version is unverified, and finding 2 in particular is version-sensitive. Re-run this probe there
  before Stage B (T116).