Output contract

This section defines the Interpreter Output Contract, which specifies the structure and semantics of data returned by an interpreter to the Courier Runner.

An interpreter MUST return exactly one JSON object through standard output (stdout) that conforms to this contract. The Courier Runner MUST treat this object as the authoritative result of the interpreter invocation.

Transport and framing

• The interpreter MUST serialize the Interpreter Output Contract as a single JSON object.
• The JSON document MUST be written to standard output (stdout).
• The interpreter MUST NOT emit multiple JSON documents or stream partial JSON results.
• The Courier Runner MUST read the entirety of stdout and parse it as a single JSON object.
• The interpreter MUST close stdout to signal completion of output.

Unstructured diagnostic output MAY be written to standard error (stderr), but stderr MUST NOT be used as the sole carrier of structured results or required outputs.

Output object structure

The Interpreter output contract is a JSON object returned in its entirety through standard output. The following example illustrates the overall structure of a valid interpreter response. This example is non-normative and is provided for clarity only.

{
  "command": {
    "command": "exec",
    "profile": "/tmp/compliance-profiles/cis-linux",
    "target": "ssh://admin@server.example.com"
  },
  "error": "",
  "output": {
    "reportPath": "/tmp/inspec-reports/report-CIS-1.2.3.json",
    "executionTime": 45.3,
    "controlsExecuted": 12,
    "controlsPassed": 10,
    "controlsFailed": 2,
    "rawInterpreterOutput": "Profile: CIS Linux Benchmark\nVersion: 1.0.0\n..."
  },
  "runContext": {
    "version": "1.2.0"
  },
  "status": 0
}

The object contains a small set of well-defined top-level fields. Some fields are required, while others are optional and may be omitted depending on execution outcome and interpreter behavior. The semantics and requirements for each field are defined in the following subsections.

Required fields

• status (integer) The exit status of the interpreter execution.

  • 0 indicates successful execution.
  • Any non-zero value indicates failure.

  The interpreter process exit code SHOULD match the value of status.

• output (object) Interpreter-specific structured output data. This object MUST be present, even in failure scenarios. It MAY be an empty object.

Optional fields

• command (string | object | array) An echo of the command that was executed. This field SHOULD reflect the interpreter-specific command payload received in the invocation contract. It exists to support debugging, verification, and traceability.

• error (string) A human-readable error message describing the reason for failure.

  • This field SHOULD be present if status is non-zero.
  • This field MAY be omitted or empty on success.

• runContext (object) Execution metadata supplied by the interpreter. If present, it MAY include:

  • version: the version of the interpreter implementation that executed the command.

Semantics of output

The output object is the primary mechanism by which interpreters return structured data, artifacts, and extractable values.

• The output object MAY contain any JSON-serializable keys and values.

• The schema of output is interpreter-defined and SHOULD be published through the interpreter contract discovery mechanism (refer to the Interpreter discovery section for further details).

• Values in output MAY represent:

  • Structured reports
  • Metrics
  • Artifact references (for example, file paths)
  • Execution summaries
  • Raw tool output

Interpreters SHOULD include raw underlying tool output for diagnostic purposes using stable, well-known keys. At a minimum, interpreters SHOULD provide equivalents of:

• rawInterpreterOutput - raw standard output of the underlying tool
• rawInterpreterError - raw standard error of the underlying tool

These keys enable reliable extraction, debugging, and audit trails.

Relationship to job context and output extraction

The Courier Runner MAY apply outputFieldRules defined in the job step to extract values from:

• the output object,
• raw interpreter output,
• referenced files,
• or the exit status.

Extracted values MAY be written into the job context and made available to subsequent steps as inputs or conditions.

Interpreters SHOULD ensure that any value intended for downstream consumption is either:

• directly present in the output object, or
• referenced by a stable identifier included in the output object.

Failure semantics

• A non-zero status value indicates interpreter failure.
• Failure MAY still return partial results in output.
• The Courier Runner MUST NOT assume that the absence of error implies success.
• The Courier Runner MUST rely on status as the authoritative success or failure signal (refer to the Validation and parsing section for further details).

Validity requirements

• The interpreter MUST emit valid JSON.
• The interpreter MUST include all required fields.
• Invalid or malformed output MUST be treated as interpreter failure by the Courier Runner.