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

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:

{
  "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, including properties like id, name, fill, and text
• Excel cells – Defined in schemas/help/xlsx/cell.json, containing cell values, formulas, and formatting metadata
• PowerPoint pictures – Defined in schemas/help/pptx/picture.json, describing image references, dimensions, and positioning data

The top-level schema description in 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.

The error envelope structure is:

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

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

Output:

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

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

Output:

{
  "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 and 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 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 constructs this envelope, and src/officecli/ResidentServer.cs writes it to stdout with a non-zero exit code.

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