# OfficeCLI JSON Output Schema for AI Error Recovery: A Complete Technical Guide

> Master the OfficeCLI JSON output schema for AI error recovery. Learn how OfficeCLI's structured data helps AI detect failures and auto-correct, streamlining your workflow.

- Repository: [OfficeAI/OfficeCLI](https://github.com/iofficeai/OfficeCLI)
- Tags: api-reference
- Published: 2026-08-04

---

**OfficeCLI returns a deterministic JSON envelope with `success`, `data`, `error`, and `suggestions` fields, enabling AI agents to detect failures programmatically and auto-correct without parsing unstructured text.**

OfficeCLI was purpose-built for autonomous AI agents manipulating Office documents. Every command that supports `--json` adheres to a strict schema contract defined in the source code. Understanding this **OfficeCLI JSON output schema for AI error recovery** lets developers build self-healing automation pipelines that interpret failures, extract actionable guidance, and retry with corrected parameters.

## The OfficeCLI JSON Envelope Structure

The foundation of AI-driven error recovery is the envelope's predictable structure. When you append `--json` to any OfficeCLI command, the output follows this exact contract:

| Field | Type | Purpose |
|-------|------|---------|
| `success` | boolean | `true` if operation completed; `false` if any error occurred |
| `data` | object | Command-specific payload (element details, lists, paths) |
| `error` | object | Present only when `success: false`; contains `code`, `error`, `suggestion` |
| `warnings` | array | Non-fatal notices that don't halt execution |

This design lives in [`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentServer.cs), where the `OutputFormatter.WrapEnvelope*` methods construct the response. The core logic at lines 842-870 handles the envelope assembly and exit code mapping:

- **Exit code 0**: `success: true`, operation completed
- **Exit code 1**: `success: false`, operation failed with structured error
- **Exit code 2**: `success: true` but `warnings` contains unsupported/deprecated notices

## Designing AI-Friendly Error Recovery Loops

The `suggestion` field is what distinguishes OfficeCLI from conventional CLI tools. When an operation fails, the error object includes a machine-actionable hint enabling automatic correction.

### Example: Recovering from a Missing Slide

```bash

# Step 1: Attempt to access non-existent slide

officecli get report.pptx /slide[99]/shape[1] --json

```

Response:

```json
{
  "success": false,
  "error": {
    "error": "Slide 50 not found (total: 8)",
    "code": "not_found",
    "suggestion": "Valid Slide index range: 1-8"
  }
}

```

The AI agent parses this, extracts the valid range from `suggestion`, and queries available slides:

```bash

# Step 2: List valid slides with depth-limited metadata

officecli get report.pptx /slide --depth 1 --json

```

Response:

```json
{
  "success": true,
  "data": [
    { "tag": "slide", "path": "/slide[1]" },
    { "tag": "slide", "path": "/slide[2]" },
    { "tag": "slide", "path": "/slide[3]" },
    { "tag": "slide", "path": "/slide[4]" },
    { "tag": "slide", "path": "/slide[5]" },
    { "tag": "slide", "path": "/slide[6]" },
    { "tag": "slide", "path": "/slide[7]" },
    { "tag": "slide", "path": "/slide[8]" }
  ]
}

```

```bash

# Step 3: Retry with validated path

officecli get report.pptx /slide[1]/shape[1] --json

```

This pattern—attempt, parse error, query valid options, retry—requires no human intervention when the OfficeCLI JSON output schema for AI error recovery is implemented correctly.

## Nested Envelope Prevention

A critical implementation detail in [`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentServer.cs) (lines 845-863) prevents **double-wrapping**. Commands that natively produce envelopes (`get`, `add`, `dump`) are returned untouched. Other outputs are wrapped via `OutputFormatter.WrapEnvelope*`. This ensures you never receive malformed nesting like:

```json
{
  "success": true,
  "data": {
    "success": true,
    "data": { ... }
  }
}

```

The detection logic checks if the inner result already contains `success` and `data` fields before applying the envelope.

## Complete Code Examples

### Successful Element Retrieval

```bash
officecli get deck.pptx /slide[1]/shape[1] --json

```

```json
{
  "success": true,
  "data": {
    "tag": "shape",
    "path": "/slide[1]/shape[1]",
    "attributes": {
      "name": "TextBox 1",
      "text": "Hello"
    }
  }
}

```

### Validation Error with Corrective Guidance

```bash
officecli set deck.pptx '/slide[1]/shape[1]' --prop color=invalidhex --json

```

```json
{
  "success": false,
  "error": {
    "error": "Invalid color value 'invalidhex'",
    "code": "invalid_value",
    "suggestion": "Use a hex string like #FF0000 or a named color"
  }
}

```

The `suggestion` here can be parsed to extract valid formats, or the agent can reference [`schemas/help/_shared/validation.json`](https://github.com/iOfficeAI/OfficeCLI/blob/main/schemas/help/_shared/validation.json) for machine-readable constraint definitions.

### Warning-Permissive Operations

```bash
officecli add deck.pptx / --type shape --prop fill=transparent --json

```

```json
{
  "success": true,
  "data": {
    "path": "/slide[1]/shape[2]"
  },
  "warnings": [
    {
      "warning": "'transparent' is not a supported fill; defaulting to solid"
    }
  ]
}

```

Note the **exit code 0** despite warnings. Only unsupported warnings trigger exit code 2, allowing agents to distinguish between cosmetic issues and compatibility problems.

## Key Source Files for Schema Implementation

| File | Lines | Responsibility |
|------|-------|--------------|
| [`src/officecli/ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/ResidentServer.cs) | 842-870 | Envelope construction, exit code mapping, success/warning/error triage |
| [`src/officecli/ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/ResidentServer.cs) | 845-863 | Nested envelope detection and wrapping logic |
| [`src/officecli/Help/SchemaHelpFlatRenderer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Help/SchemaHelpFlatRenderer.cs) | — | Renders `--json` help documenting per-command envelope contracts |
| [`schemas/help/_shared/validation.json`](https://github.com/iOfficeAI/OfficeCLI/blob/main/schemas/help/_shared/validation.json) | — | Machine-readable error codes and validation flags |
| [`README.md`](https://github.com/iOfficeAI/OfficeCLI/blob/main/README.md) | JSON Output Schemas section | Human-readable schema specification with examples |

## Building Self-Healing Agent Workflows

To maximize the OfficeCLI JSON output schema for AI error recovery:

1. **Always use `--json`** for programmatic consumption—never parse stdout/stderr directly
2. **Check `success` before `data`** to avoid null reference errors
3. **Implement `suggestion` parsers** for common error codes: `not_found`, `invalid_value`, `path_syntax`, `permission_denied`
4. **Log but don't halt on `warnings`** unless exit code 2 indicates unsupported features
5. **Cache schema definitions** from `schemas/help/_shared/*.json` to validate commands before execution

The deterministic contract between OfficeCLI and consuming agents eliminates the fragility of screen-scraping, enabling reliable automation at scale.

## Summary

- OfficeCLI's JSON envelope provides **deterministic success/failure signaling** through `success`, `data`, `error`, and `warnings` fields
- **Exit codes mirror envelope state**: 0 for success, 1 for errors, 2 for unsupported warnings
- The `error.suggestion` field enables **automatic error recovery** without human intervention
- **Nested envelope prevention** in [`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentServer.cs) ensures clean, predictable output structure
- AI agents can implement **self-healing loops**: attempt, parse error, query valid alternatives, retry

## Frequently Asked Questions

### What error codes does OfficeCLI use in the JSON envelope?

OfficeCLI uses descriptive string codes in `error.code` including `not_found` for missing elements, `invalid_value` for malformed properties, `path_syntax` for malformed XPath-style queries, and `permission_denied` for locked documents. These codes are defined in [`schemas/help/_shared/validation.json`](https://github.com/iOfficeAI/OfficeCLI/blob/main/schemas/help/_shared/validation.json) and documented in the README's JSON Output Schemas section.

### How does OfficeCLI prevent double-wrapped JSON envelopes?

Before wrapping output, OfficeCLI checks whether the inner result already contains `success` and `data` fields. Commands like `get`, `add`, and `dump` that natively return envelopes are passed through unchanged. This logic resides in [`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentServer.cs) lines 845-863, ensuring you never receive nested structures.

### Can AI agents trust the `suggestion` field for automatic correction?

Yes. The `suggestion` field is machine-generated and follows consistent patterns: range specifications ("Valid Slide index range: 1-8"), format examples ("Use a hex string like #FF0000"), or alternative commands. Agents can parse these with regex or simple string matching to extract actionable values.

### What's the difference between warnings and errors in OfficeCLI?

**Errors** set `success: false`, populate the `error` object, and exit with code 1—halting dependent operations. **Warnings** appear in the `warnings` array with `success: true`, indicating the operation completed but with caveats. Exit code 2 specifically indicates unsupported warnings that may affect compatibility.