# OfficeCLI JSON Output Schemas for Get, Query, and Error Responses

> Understand OfficeCLI JSON output schemas for get, query, and error responses. Learn how iOfficeAI/OfficeCLI structures data and handles errors for efficient integration.

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

---

**OfficeCLI returns structured JSON outputs for get and query operations as arrays of document nodes defined in schema files under `schemas/help/`, while errors return an enveloped object with `code` and `message` fields generated by `OutputFormatter.WrapErrorEnvelope`.**

The **iOfficeAI/OfficeCLI** repository provides a command-line interface for manipulating Office documents, and when you append the `--json` flag to any **get** or **query** command, the tool emits machine-readable responses. Understanding these JSON output schemas is essential for integrating OfficeCLI into automated workflows and CI/CD pipelines.

## Get and Query Response Schema

When retrieving document elements via `officecli get` or `officecli query` with the `--json` flag, the CLI returns a JSON array (or single object) of **document nodes**. Each node follows a consistent base structure augmented by format-specific properties.

### Generic Node Structure

Every node in the JSON output includes two mandatory fields defined in the base schema:

```json
{
  "type": "string",
  "path": "string"
}

```

- **`type`** – Identifies the element category (e.g., `"shape"`, `"cell"`, `"picture"`)
- **`path`** – The OOXML selector path that located the node within the document

These generic fields appear in all responses, regardless of whether you are querying a Word document, Excel spreadsheet, or PowerPoint presentation.

### Format-Specific Properties

Following the generic fields, each node includes element-specific keys defined in dedicated schema files under `schemas/help/`. The exact properties vary by file format and element type:

- **Word shapes** – Defined in [`schemas/help/docx/shape.json`](https://github.com/iOfficeAI/OfficeCLI/blob/main/schemas/help/docx/shape.json), including properties like `id`, `name`, `fill`, and `text`
- **Excel cells** – Defined in [`schemas/help/xlsx/cell.json`](https://github.com/iOfficeAI/OfficeCLI/blob/main/schemas/help/xlsx/cell.json), containing cell values, formulas, and formatting metadata
- **PowerPoint pictures** – Defined in [`schemas/help/pptx/picture.json`](https://github.com/iOfficeAI/OfficeCLI/blob/main/schemas/help/pptx/picture.json), describing image references, dimensions, and positioning data

The top-level schema description in [`schemas/help/_schema.json`](https://github.com/iOfficeAI/OfficeCLI/blob/main/schemas/help/_schema.json) governs the overall structure of these definition files.

## Error Response Schema

When a command fails, OfficeCLI does not write error details to **stderr**. Instead, it returns an enveloped JSON error object to **stdout** via the `OutputFormatter.WrapErrorEnvelope` method in [`src/officecli/Core/OutputFormatter.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Core/OutputFormatter.cs).

The error envelope structure is:

```json
{
  "error": {
    "code": 1,
    "message": "Error: Path not found: nonexistent[foo]"
  }
}

```

- **`code`** – A non-zero integer representing the exit status
- **`message`** – Human-readable error text describing the failure condition

The final JSON response assembly occurs in [`src/officecli/ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/ResidentServer.cs), which writes the complete envelope to the client stream regardless of whether the operation succeeded or failed.

## Practical Examples

### Successful Document Retrieval

Querying a specific shape in a Word document returns an array with the node’s complete property set:

```bash
officecli get mydoc.docx /body/shape[3] --json

```

**Output:**

```json
[
  {
    "type": "shape",
    "path": "/body/shape[3]",
    "id": "2",
    "name": "MyShape",
    "fill": "FF0000",
    "text": "Hello"
  }
]

```

### Failed Query with Error Envelope

Attempting to query a nonexistent path triggers the error schema:

```bash
officecli query mydoc.docx "nonexistent[foo]" --json

```

**Output:**

```json
{
  "error": {
    "code": 1,
    "message": "Error: Path not found: nonexistent[foo]"
  }
}

```

Notice that the error details appear in the JSON envelope rather than as plain text in **stderr**, making programmatic error handling straightforward.

## Summary

- **OfficeCLI JSON output schemas** are activated by the `--json` flag on get and query commands.
- **Successful responses** return arrays of nodes with `type` and `path` fields, extended by format-specific properties defined in `schemas/help/docx/`, `schemas/help/xlsx/`, and `schemas/help/pptx/`.
- **Error responses** use a standardized envelope format generated by `OutputFormatter.WrapErrorEnvelope`, containing an `error` object with `code` and `message` fields.
- **Implementation files** [`src/officecli/Core/OutputFormatter.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Core/OutputFormatter.cs) and [`src/officecli/ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/ResidentServer.cs) handle the final serialization and delivery of both success and error JSON payloads.

## Frequently Asked Questions

### How do I enable JSON output in OfficeCLI?

Append the `--json` flag to any **get** or **query** command. When this flag is present, OfficeCLI formats all output—whether successful document nodes or error messages—as structured JSON instead of human-readable text.

### Where are the JSON schemas defined in the source code?

Schema definitions reside in the `schemas/help/` directory. The file [`schemas/help/_schema.json`](https://github.com/iOfficeAI/OfficeCLI/blob/main/schemas/help/_schema.json) describes the metadata format, while subdirectories like `schemas/help/docx/`, `schemas/help/xlsx/`, and `schemas/help/pptx/` contain element-specific definitions for shapes, cells, and pictures respectively.

### What fields are included in every JSON node response?

Every node returned by get or query operations includes a `type` string identifying the element category and a `path` string containing the OOXML selector that located the node. Additional properties vary by document format and are defined in the corresponding schema files.

### How does OfficeCLI handle errors when --json is specified?

Instead of writing to **stderr**, OfficeCLI returns a JSON envelope containing an `error` object with `code` and `message` fields. The `OutputFormatter.WrapErrorEnvelope` method in [`src/officecli/Core/OutputFormatter.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Core/OutputFormatter.cs) constructs this envelope, and [`src/officecli/ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/ResidentServer.cs) writes it to **stdout** with a non-zero exit code.