# OfficeCLI JSON Output Schema for Automation: Complete Technical Reference

> Leverage the OfficeCLI JSON output schema for robust automation. Get machine-readable, validated data for seamless integration with your tools.

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

---

**OfficeCLI returns a strict JSON envelope for every command when you add `--json`, enabling reliable machine-readable automation with full schema validation.**

The OfficeCLI repository (iOfficeAI/OfficeCLI) provides a **machine-readable JSON envelope** for every command when the `--json` flag is supplied. This JSON follows a strict JSON-Schema that lives in `schemas/help/`, defining elements, properties, path addressing, and command-level metadata. Understanding this schema is essential for building robust automation pipelines that integrate with Word, Excel, and PowerPoint documents.

## Core Schema Architecture

### The Master Schema: [`_schema.json`](https://github.com/iOfficeAI/OfficeCLI/blob/main/_schema.json)

The top-level schema at [`schemas/help/_schema.json`](https://github.com/iOfficeAI/OfficeCLI/blob/main/schemas/help/_schema.json) serves as the foundation for all element-specific schemas. Every element schema references this file via a `$schema` pointer (e.g., `"$schema": "../_schema.json"`).

According to the source, this is the "Capability schema for one (format, element) pair… consumed by `officecli <format> <op> <element> --help --json`"【source†L5-L7】.

The schema defines five critical concepts:

| Concept | Purpose | Schema Location |
|---------|---------|-----------------|
| **element** | Logical object name (e.g., `paragraph`, `cell`) | `"element": { "type": "string", ... }` in [`_schema.json`](https://github.com/iOfficeAI/OfficeCLI/blob/main/_schema.json)【source†L183-L185】 |
| **properties** | Canonical attributes with types, aliases, and read-back formats | `"properties"` sections in element schemas (e.g., [`docx/paragraph.json`](https://github.com/iOfficeAI/OfficeCLI/blob/main/docx/paragraph.json) line 32)【source†L32-L33】 |
| **path forms** | Positional `/body/paragraph[N]` vs. keyed `/chart[@role=value]` addressing | `"paths"` and `"keyedPaths"` in [`_schema.json`](https://github.com/iOfficeAI/OfficeCLI/blob/main/_schema.json)【source†L54-L68】 |
| **read-back format** | Textual representation in `Get` output (`"boolean"`, `"enum"`, etc.) | `"format` field【source†L169-L170】 |
| **enforcement** | Validation strictness (`strict` = test failure, `report` = log drift) | `"enforcement"` field【source†L174-L175】 |

## JSON Envelope Structure

When you run any OfficeCLI command with `--json`, the output wraps in a standard envelope. The `CommandBuilder` class (C#) builds this structure by:

1. Validating input against the element schema
2. Executing the operation (`add`, `set`, `get`, `remove`)
3. Wrapping results in the envelope format

```json
{
  "status": "ok",
  "command": "get",
  "format": "docx",
  "element": "paragraph",
  "path": "/body/paragraph[3]",
  "data": {
    "results": [
      {
        "align": "center",
        "text": "Automation paragraph"
      }
    ]
  }
}

```

The envelope fields (`status`, `command`, `format`, `element`, `path`) come from the **generic schema**, while `data.results` objects follow **element-specific schemas**.

## Element Schema Example: Word Paragraph

The [`schemas/help/docx/paragraph.json`](https://github.com/iOfficeAI/OfficeCLI/blob/main/schemas/help/docx/paragraph.json) file demonstrates how properties are defined. Here's the `align` property specification:

```json
"align": {
  "type": "enum",
  "enum": ["left", "center", "right", "justify"],
  "description": "horizontal alignment of the paragraph",
  "enforcement": "strict"
}

```

This property enforces strict validation—any value outside the enum array causes a test failure. The definition appears at line 53 in the source file【source†L53-L55】.

## Automation Examples

### CLI: Get Excel Cell Value with JSON Output

```bash
officecli xlsx get /Sheet1/cell[A1] --json

```

Response structure:

```json
{
  "status":"ok",
  "command":"get",
  "format":"xlsx",
  "element":"cell",
  "path":"/Sheet1/cell[A1]",
  "data":{
    "results":[{
      "value":"42",
      "type":"number"
    }]
  }
}

```

The `value` (string) and `type` (enum) properties are defined in [`schemas/help/xlsx/cell.json`](https://github.com/iOfficeAI/OfficeCLI/blob/main/schemas/help/xlsx/cell.json).

### CLI: Set Word Paragraph Alignment

```bash
officecli docx set /body/paragraph[2] --prop align=center --json

```

Success response:

```json
{
  "status":"ok",
  "command":"set",
  "format":"docx",
  "element":"paragraph",
  "path":"/body/paragraph[2]",
  "data":{"results":[]}
}

```

The `align` value is validated against the enum from [`docx/paragraph.json`](https://github.com/iOfficeAI/OfficeCLI/blob/main/docx/paragraph.json) before execution.

### Python SDK: Programmatic JSON Access

Both Python and Node SDKs expose a `send` method that mirrors CLI behavior. Use `as_json=False` to receive the identical JSON envelope:

```python
from officecli import OfficeCLI

cli = OfficeCLI()
response = cli.send({
    "command": "get",
    "format": "docx",
    "element": "paragraph",
    "path": "/body/paragraph[3]"
}, as_json=False)

print(response["data"]["results"][0]["align"])

# → center

```

This matches the CLI's `--json` output exactly, as documented in the Python SDK README【source†L81-L102】.

### Node SDK: Add PowerPoint Chart

```javascript
const { OfficeCLI } = require("@officecli/sdk");

(async () => {
  const cli = new OfficeCLI();
  const resp = await cli.send({
    command: "add",
    format: "pptx",
    element: "chart",
    parent: "/slide[1]",
    type: "column",
    data: { series1: { name: "Sales", values: [10,20,30] } }
  }, { asJson: false });

  console.log(resp);
})();

```

The response follows the same envelope structure as `officecli pptx add … --json`.

## Schema Enforcement Levels

The `enforcement` field controls validation behavior:

- **`strict`** — Invalid values cause immediate test/pipeline failure
- **`report`** — Invalid values are logged but execution continues

This distinction matters for CI/CD integrations where you may want permissive parsing with audit trails versus hard failures on schema drift.

## Key Source Files for Automation Developers

| Path | Purpose |
|------|---------|
| [`schemas/help/_schema.json`](https://github.com/iOfficeAI/OfficeCLI/blob/main/schemas/help/_schema.json) | Master schema for elements, properties, paths, and enforcement rules |
| [`schemas/help/docx/paragraph.json`](https://github.com/iOfficeAI/OfficeCLI/blob/main/schemas/help/docx/paragraph.json) | Reference element schema (Word) |
| [`schemas/help/xlsx/cell.json`](https://github.com/iOfficeAI/OfficeCLI/blob/main/schemas/help/xlsx/cell.json) | Reference element schema (Excel) |
| [`src/officecli/CommandBuilder.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/CommandBuilder.cs) | CLI implementation; injects `--json` and formats output |
| [`sdk/python/README.md`](https://github.com/iOfficeAI/OfficeCLI/blob/main/sdk/python/README.md) | Python SDK `send(..., as_json=False)` documentation |
| [`sdk/node/README.md`](https://github.com/iOfficeAI/OfficeCLI/blob/main/sdk/node/README.md) | Node SDK JSON envelope access |
| [`npm/README.md`](https://github.com/iOfficeAI/OfficeCLI/blob/main/npm/README.md) | NPM package with CLI `--json` examples |

## Summary

- OfficeCLI JSON output schema provides **machine-readable envelopes** for all commands via `--json`
- **[`_schema.json`](https://github.com/iOfficeAI/OfficeCLI/blob/main/_schema.json)** defines the master contract; element schemas reference it with `$schema` pointers
- Envelope separates **metadata** (`status`, `command`, `format`, `element`, `path`) from **data results**
- **Property definitions** include type, enum constraints, description, and enforcement level
- **Python and Node SDKs** mirror CLI output through `as_json=False` / `asJson: false` parameters
- **Path addressing** supports both positional (`[N]`) and keyed (`[@attr=value]`) forms

## Frequently Asked Questions

### How do I access the raw JSON schema definitions?

Clone the iOfficeAI/OfficeCLI repository and navigate to `schemas/help/`. The [`_schema.json`](https://github.com/iOfficeAI/OfficeCLI/blob/main/_schema.json) file contains the master definitions; element-specific schemas live in subdirectories like `docx/` and `xlsx/`. Each element file declares `"$schema": "../_schema.json"` to inherit the base structure.

### What's the difference between `strict` and `report` enforcement?

`strict` enforcement causes validation failures that halt execution—use this for production pipelines requiring schema compliance. `report` enforcement logs schema violations without stopping execution—use this for migration scenarios or when accepting legacy document formats. This field appears in property definitions at line 174 of [`_schema.json`](https://github.com/iOfficeAI/OfficeCLI/blob/main/_schema.json)【source†L174-L175】.

### Can I use the JSON output without installing the CLI?

Yes. Both official SDKs (Python and Node) provide the same JSON envelope through their `send` methods. Pass `as_json=False` (Python) or `asJson: false` (Node) to receive structured data without shelling out to the CLI binary. The SDKs handle schema validation internally before returning results.