OfficeCLI JSON Output Schema for Automation: Complete Technical Reference

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

The top-level schema at 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【source†L183-L185】
properties	Canonical attributes with types, aliases, and read-back formats	"properties" sections in element schemas (e.g., 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【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

{
  "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 file demonstrates how properties are defined. Here's the align property specification:

"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

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

Response structure:

{
  "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.

CLI: Set Word Paragraph Alignment

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

Success response:

{
  "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 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:

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

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	Master schema for elements, properties, paths, and enforcement rules
schemas/help/docx/paragraph.json	Reference element schema (Word)
schemas/help/xlsx/cell.json	Reference element schema (Excel)
src/officecli/CommandBuilder.cs	CLI implementation; injects --json and formats output
sdk/python/README.md	Python SDK send(..., as_json=False) documentation
sdk/node/README.md	Node SDK JSON envelope access
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 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 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【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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}