OfficeCLI JSON Output Schema: How Command Responses Are Structured

OfficeCLI formats every command result as JSON when the --json flag is used, following a versioned master schema that defines consistent top-level fields including format, element, operations, paths, properties, and children across all DOCX, XLSX, and PPTX document types.

The iOfficeAI/OfficeCLI repository provides a command-line interface for manipulating Office documents, and when you append the --json flag to any command, the tool emits structured data rather than human-readable text. Understanding the JSON output schema is essential for building automation scripts, CI/CD pipelines, or integrations that programmatically parse workbook metadata, paragraph styles, or presentation elements.

The Master Schema Contract

All OfficeCLI JSON responses adhere to a single, versioned master schema located at schemas/help/_schema.json. This file serves as the contract that every element-specific schema must follow, describing the top-level fields and validation rules for properties, types, and allowed values.

The master schema defines the structural contract for six core fields that appear in every response:

• format – The document type (docx, xlsx, or pptx)
• element – The specific Office element being queried or modified
• operations – Supported CRUD operations (add, set, get, query, remove)
• paths – Positional and stable path patterns accepted by the CLI
• properties – The actual data payload containing element-specific values
• children – Descriptors for nested elements and their cardinality

Element-Specific Schemas by Document Type

For each supported document type, OfficeCLI maintains dedicated schema files that extend the master schema and enumerate concrete properties. These files live in format-specific subdirectories under schemas/help/.

XLSX Workbook Schema

The schemas/help/xlsx/workbook.json file defines metadata properties for Excel files, including author, title, calculation mode, and date1904 settings. It also declares the sheet element as a valid child with cardinality constraints.

DOCX Paragraph Schema

The schemas/help/docx/paragraph.json file specifies paragraph styling attributes such as alignment, indentation, spacing, and text runs. It defines the run element as a child that can appear zero or more times within a paragraph.

PPTX Table Schema

The schemas/help/pptx/table.json file describes table layout properties including cell fills, row counts, column counts, and cell-specific attributes. It supports operations on individual cells within slide tables.

Standard JSON Response Structure

When serialized by the core formatter, every JSON response conforms to this consistent structure derived from _schema.json:

{
  "format": "docx|xlsx|pptx",
  "element": "<element-name>",
  "operations": {
    "add": true|false,
    "set": true|false,
    "get": true|false,
    "query": true|false,
    "remove": true|false
  },
  "paths": {
    "positional": ["/<path-segment>..."],
    "stable": ["/<stable-path>..."]
  },
  "properties": {
    "<prop-name>": "<value>"
  },
  "children": [
    {
      "element": "<child-element>",
      "pathSegment": "<segment>",
      "cardinality": "0..n|1..n|1|0..1",
      "key": "<key-attr>",
      "keyValues": [ "val1", "val2" ]
    }
  ]
}

The properties object contains only the values requested by the command, while the operations object indicates which actions are valid for the specific element type.

Runtime Schema Processing

The CLI implements a two-stage pipeline for schema handling that ensures type-safe JSON generation.

Schema Loading

The src/officecli/Help/SchemaHelpLoader.cs class locates and parses JSON schema files at program startup, caching the master schema and all element-specific definitions. This loader validates that requested elements have corresponding schema files before command execution.

Output Formatting

The src/officecli/Core/OutputFormatter.cs class queries the appropriate schema based on document type and element name, extracts the requested properties from the Office document model, and serializes the result into the standard JSON structure. This component ensures that all emitted JSON strictly conforms to the schema contract defined in _schema.json.

Practical Command Examples

Querying XLSX Workbook Metadata

To retrieve workbook-level properties with the JSON output schema:

officecli xlsx get workbook --json

Sample output:

{
  "format": "xlsx",
  "element": "workbook",
  "operations": { "add": false, "set": true, "get": true, "query": true, "remove": false },
  "paths": { "positional": ["/"] },
  "properties": {
    "author": "Alice",
    "title": "Q1 Report",
    "calc.mode": "manual",
    "workbook.date1904": false,
    "revisionNumber": "3"
  },
  "children": [
    { "element": "sheet", "pathSegment": "{SheetName}", "cardinality": "1..n" }
  ]
}

Setting DOCX Paragraph Properties

When modifying paragraph alignment:

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

Sample output:

{
  "format": "docx",
  "element": "paragraph",
  "operations": { "add": false, "set": true, "get": true, "query": false, "remove": false },
  "paths": { "positional": ["/body/p[N]"] },
  "properties": {
    "alignment": "center"
  },
  "children": [
    { "element": "run", "pathSegment": "r[N]", "cardinality": "0..n" }
  ]
}

Adding PPTX Table Cells

To add a cell to a presentation table:

officecli pptx add cell /slide[1]/table[0]/row[1] --prop text="Hello" --json

Sample output:

{
  "format": "pptx",
  "element": "cell",
  "operations": { "add": true, "set": true, "get": true, "query": false, "remove": true },
  "paths": { "positional": ["/slide[N]/table[K]/row[R]/cell[C]"] },
  "properties": {
    "text": "Hello"
  }
}

Querying DOCX Shapes

To query all shapes in a Word document:

officecli docx query shape --json

Sample output:

{
  "format": "docx",
  "element": "shape",
  "operations": { "add": false, "set": true, "get": true, "query": true, "remove": false },
  "paths": { "positional": ["/body/drawings/drawing[N]/shape[S]"] },
  "properties": {
    "type": "picture",
    "description": "Company logo"
  },
  "children": []
}

Summary

• OfficeCLI JSON output schema is governed by schemas/help/_schema.json, which mandates six top-level fields for every response.
• Element-specific schemas extend the master contract for DOCX, XLSX, and PPTX elements, defining concrete properties and valid child elements in files like workbook.json, paragraph.json, and table.json.
• Runtime components SchemaHelpLoader.cs and OutputFormatter.cs handle schema parsing and JSON serialization, ensuring all --json outputs conform to the versioned contract.
• Consistent structure across commands enables reliable parsing by automation tools, with the operations field indicating available CRUD actions and paths providing stable addressing patterns.

Frequently Asked Questions

What fields are guaranteed in every OfficeCLI JSON response?

Every JSON response includes six mandatory fields defined in the master schema: format (document type), element (target entity), operations (supported CRUD flags), paths (addressing patterns), properties (data payload), and children (nested element descriptors). These fields appear even when empty, ensuring predictable parsing by downstream tools.

How does OfficeCLI determine which schema to use for validation?

The SchemaHelpLoader.cs class in src/officecli/Help/ maps the combination of document format (docx/xlsx/pptx) and element name to a specific JSON file under schemas/help/. For example, a command targeting an XLSX workbook loads schemas/help/xlsx/workbook.json, while the master schema in schemas/help/_schema.json provides the structural contract that all element schemas must satisfy.

Can I rely on the JSON schema stability across OfficeCLI versions?

Yes, the schema is versioned and designed for machine readability. The master schema defines strict typing and cardinality rules, and OutputFormatter.cs ensures that all emitted JSON conforms to these contracts. However, you should pin your integration to specific OfficeCLI releases, as new properties may be added to element schemas in future versions while maintaining backward compatibility for existing fields.

Where does the actual JSON serialization happen in the codebase?

The OutputFormatter.cs file in src/officecli/Core/ contains the serialization logic. It queries the loaded schema definitions, extracts the requested properties from the Office document object model, and constructs the JSON object according to the standard structure. This class is invoked by the command handlers orchestrated in src/officecli/CommandBuilder.cs whenever the --json flag is present.

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