Skip to content

REQ-F-059: JSON5 Input Normalization

Tier: Framework-Automatic | Priority: P1

Source: §67 Agent-Generated Input Syntax Rejection

Addresses: Severity: High / Token Spend: High / Time: Medium / Context: Low

Description

The framework MUST use a forgiving JSON parser for all structured input flags (--config, --filter, --data, --raw-payload, and any flag declared with type: json). The parser MUST accept: trailing commas in objects and arrays, single-line // comments, block /* */ comments, and unquoted keys. When strict JSON parsing is required (e.g., for schema validation), the framework MUST normalize the input to strict JSON first. If normalization fails, the error MUST include a corrected_input field showing the normalized form that would have been accepted.

Acceptance Criteria

  • --config '{"key": "value",}' (trailing comma) is accepted and parsed correctly
  • --config '{"key": "value" /* comment */}' is accepted and parsed correctly
  • A malformed input that cannot be normalized produces an error with corrected_input showing the closest valid form
  • Normalized inputs pass JSON schema validation identically to equivalent strict JSON

Schema

Type: response-envelope.md

When normalization fails, the framework emits an ARG_ERROR (3) response with error.code: "INVALID_JSON" and a corrected_input field in error.detail or as a top-level extension.

Wire Format

{
  "ok": false,
  "data": null,
  "error": {
    "code": "INVALID_JSON",
    "message": "Input could not be normalized to valid JSON",
    "retryable": true,
    "phase": "validation",
    "corrected_input": "{\"key\": \"value\"}",
    "suggestion": "Use the corrected_input value to retry"
  },
  "warnings": [],
  "meta": { "duration_ms": 3 }
}

Example

Framework-Automatic: no command author action needed. The framework substitutes its forgiving JSON parser for all flags declared type: json.

# Trailing comma — accepted
$ mytool deploy --config '{"env": "prod",}' --json
{ "ok": true, "data": { ... }, ... }

# Block comment — accepted
$ mytool deploy --config '{"env": /* staging */ "prod"}' --json
{ "ok": true, "data": { ... }, ... }

# Unrecoverable syntax — corrected_input provided
$ mytool deploy --config '{env prod}' --json
{
  "ok": false,
  "data": null,
  "error": {
    "code": "INVALID_JSON",
    "message": "Input could not be normalized to valid JSON",
    "corrected_input": "{\"env\": \"prod\"}",
    "retryable": true,
    "phase": "validation"
  },
  ...
}
Requirement Tier Relationship
REQ-F-004 F Provides: ResponseEnvelope shape used to return the INVALID_JSON error
REQ-F-002 F Enforces: ARG_ERROR (3) exit code guarantees zero side effects for parse failures
REQ-F-015 F Composes: JSON normalization runs during the validation phase, before execution
REQ-F-045 F Composes: hallucination pattern rejection applies after JSON normalization succeeds