Distinguish no events from missing evidence
Return an explicit import result so missing or malformed evidence cannot look like a clean dataset.
Empty is a result; failure is a different result
An empty JSON array can be a valid export with no observations. A missing file or malformed JSON means you could not read the evidence. If both conditions return an empty list, downstream reporting can accidentally describe a failed import as “no findings.”
Return one result object with Success, Events, and Error. Successful imports use a boolean true, an array of events, and an empty error string. Failed imports use false, an empty array, and a meaningful diagnostic. The caller can then decide whether to stop or publish an explicitly incomplete report.
Make catch reachable
Some PowerShell commands report non-terminating errors by default. -ErrorAction Stop promotes those errors so try / catch can handle them. Use it for both file reading and JSON parsing.
Get-Content '/home/user/empty.json' -Raw |
ConvertFrom-Json -NoEnumerate -DateKind String
-NoEnumerate preserves the top-level JSON array, including an empty one. This task accepts arrays only; a valid JSON object is still the wrong export shape. Check the parsed value with -is [System.Array] before declaring success.
Diagnostics help a human understand the failure, but they are not events. Keep them in the Error property instead of mixing them into the event collection. In later tools, avoid including secrets in diagnostic messages.
Go deeper
Get-Content '/home/user/events.json' -Raw | ConvertFrom-Json -NoEnumerate -DateKind String
Put it into practice.
Define Read-CaseEvents -Path. Read a JSON array and return one object: Success (boolean), Events (array), Error (string). Valid arrays, including [], succeed with Error empty. Missing files, malformed JSON, and non-array JSON must fail with Events empty and a non-empty Error. Do not let these expected input errors escape the function.
See an explained solution
function Read-CaseEvents {
param([string]$Path)
try {
$events = Get-Content -LiteralPath $Path -Raw -ErrorAction Stop | ConvertFrom-Json -NoEnumerate -DateKind String -ErrorAction Stop
if ($events -isnot [System.Array]) { throw 'Expected a JSON array.' }
[pscustomobject]@{ Success=$true; Events=@($events); Error='' }
}
catch { [pscustomobject]@{ Success=$false; Events=@(); Error=$_.Exception.Message } }
}
Read-CaseEvents -Path '/home/user/events.json'
The import contract separates empty evidence from unavailable evidence. NoEnumerate preserves the top-level array, and catch converts expected input failures into a result the caller can inspect.