wehub-resource-sync
8cb1f9f479
Publish SDK (PyPI) / publish (push) Waiting to run
Publish SDK (npm) / publish (@aionui/officecli-sdk) (push) Waiting to run
Publish SDK (npm) / publish (@officecli/officecli-sdk) (push) Waiting to run
Publish SDK (npm) / publish (@officecli/sdk) (push) Waiting to run
Publish SDK (npm) / publish (officecli-sdk) (push) Waiting to run
SDK smoke / smoke (windows-latest) (push) Waiting to run
SDK smoke / smoke (macos-latest) (push) Waiting to run
SDK smoke / smoke (ubuntu-latest) (push) Waiting to run
Skill parity / diff (push) Waiting to run
201 lines
9.7 KiB
JSON
201 lines
9.7 KiB
JSON
{
|
|
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
"$id": "officecli/help-schema/v1",
|
|
"title": "OfficeCLI Help Schema",
|
|
"description": "Capability schema for one (format, element) pair. Consumed by `officecli <format> <op> <element> --help --json`, contract tests, and release-time wiki generation. This is the agent-facing source of truth for what officecli can do; it is updated in the same PR as the implementation.",
|
|
"type": "object",
|
|
"required": ["format", "element", "operations", "properties"],
|
|
"properties": {
|
|
"$schema": { "type": "string", "description": "pointer to this meta file for IDE tooling; ignored at runtime" },
|
|
"format": {
|
|
"type": "string",
|
|
"enum": ["docx", "xlsx", "pptx"]
|
|
},
|
|
"element": {
|
|
"type": "string",
|
|
"description": "element name as used in CLI, e.g. shape, paragraph, cell, chart-series"
|
|
},
|
|
"parent": {
|
|
"description": "if this element only exists as a child of another, name the parent(s). Omit for top-level elements.",
|
|
"oneOf": [
|
|
{ "type": "string" },
|
|
{ "type": "array", "items": { "type": "string" } }
|
|
]
|
|
},
|
|
"note": {
|
|
"type": "string",
|
|
"description": "free-form clarification that does not fit into structured fields (e.g. schema source-of-truth pointer, invariants, caveats)"
|
|
},
|
|
"container": {
|
|
"type": "boolean",
|
|
"description": "set to true for read-only root/container entities (presentation, workbook, document, theme, slidemaster, etc.) that are navigated through but never created or mutated. Contract tests skip Add/Set assertions for containers."
|
|
},
|
|
"operations": {
|
|
"type": "object",
|
|
"description": "which top-level operations accept this element",
|
|
"properties": {
|
|
"add": { "type": "boolean" },
|
|
"set": { "type": "boolean" },
|
|
"get": { "type": "boolean" },
|
|
"query": { "type": "boolean" },
|
|
"remove": { "type": "boolean" }
|
|
},
|
|
"additionalProperties": false
|
|
},
|
|
"addParent": {
|
|
"description": "concrete CLI parent path(s) accepted by Add. Used by help renderer to print accurate `officecli add <file> <parent> --type <element>` usage. Required when the element's positional/stable paths describe the element's own addressable location (e.g. /comments/comment[N], /footnotes/footnote[N]) rather than its Add-time parent. If omitted, the renderer derives parent by dropping the last segment of paths.positional[0].",
|
|
"oneOf": [
|
|
{ "type": "string" },
|
|
{ "type": "array", "items": { "type": "string" } }
|
|
]
|
|
},
|
|
"paths": {
|
|
"type": "object",
|
|
"description": "path forms accepted when this element is addressed by index or @id",
|
|
"properties": {
|
|
"stable": { "type": "array", "items": { "type": "string" } },
|
|
"positional": { "type": "array", "items": { "type": "string" } }
|
|
},
|
|
"additionalProperties": false
|
|
},
|
|
"addressing": {
|
|
"type": "object",
|
|
"description": "used when children of this element are addressed by a key attribute (e.g. axis[@role=value]) rather than [N]. Mutually exclusive with plain positional paths.",
|
|
"required": ["key", "pathForm"],
|
|
"properties": {
|
|
"key": { "type": "string", "description": "name of the keying attribute, e.g. 'role'" },
|
|
"pathForm": { "type": "string", "description": "concrete path template, e.g. '/slide[N]/chart[N]/axis[@role=ROLE]'" },
|
|
"keyValues": { "type": "array", "items": { "type": "string" }, "description": "permitted values for the key attribute" }
|
|
},
|
|
"additionalProperties": false
|
|
},
|
|
"properties": {
|
|
"type": "object",
|
|
"description": "properties supported on this element. Key = canonical property name.",
|
|
"additionalProperties": { "$ref": "#/$defs/property" }
|
|
},
|
|
"children": {
|
|
"type": "array",
|
|
"description": "declared child element types addressable under this element in CLI paths",
|
|
"items": { "$ref": "#/$defs/childRef" }
|
|
},
|
|
"parts": {
|
|
"type": "array",
|
|
"description": "for the synthetic `raw` element only: enumerates the raw OOXML parts addressable via the `raw` and `raw-set` commands (e.g. /workbook, /Sheet1, /styles). Rendered as a 'Parts' section by the help renderer. Not used by other elements.",
|
|
"items": {
|
|
"type": "object",
|
|
"required": ["name", "desc"],
|
|
"properties": {
|
|
"name": { "type": "string", "description": "part path as accepted by `officecli raw <file> <part>` (e.g. /workbook, /Sheet1)" },
|
|
"desc": { "type": "string", "description": "one-line description of what this part contains" }
|
|
},
|
|
"additionalProperties": false
|
|
}
|
|
},
|
|
"examples": {
|
|
"type": "array",
|
|
"description": "element-level command examples (in addition to per-property examples). Used primarily by the synthetic `raw` element.",
|
|
"items": { "type": "string" }
|
|
},
|
|
"description": {
|
|
"type": "string",
|
|
"description": "element-level description (in addition to per-property descriptions). Used primarily by the synthetic `raw` element."
|
|
},
|
|
"elementAliases": {
|
|
"type": "array",
|
|
"description": "alternate element names that should resolve to this schema (e.g. `paragraph.json` declares ['p'] so that `help docx p` works the same as `help docx paragraph`). Lets path-form abbreviations used in /body/p[N], /Sheet1/col[B], etc. line up with the help index.",
|
|
"items": { "type": "string" }
|
|
}
|
|
},
|
|
"additionalProperties": false,
|
|
|
|
"$defs": {
|
|
"appliesWhen": {
|
|
"type": "object",
|
|
"description": "conditional applicability. Keys are dotted paths into sibling/ancestor state (e.g. 'chartType', 'role', 'parent.chartType'). Values are arrays of admissible values. ALL keys must match (AND).",
|
|
"additionalProperties": {
|
|
"type": "array",
|
|
"items": { "type": "string" }
|
|
}
|
|
},
|
|
"aliases": {
|
|
"description": "legacy/lenient names accepted on input, normalized to the canonical key on output. Array form = plain alias list. Object form = alias → canonical mapping (useful when one canonical has multiple aliases pointing to distinct canonical values, e.g. chartType).",
|
|
"oneOf": [
|
|
{ "type": "array", "items": { "type": "string" } },
|
|
{ "type": "object", "additionalProperties": { "type": "string" } }
|
|
]
|
|
},
|
|
"property": {
|
|
"type": "object",
|
|
"required": ["type"],
|
|
"properties": {
|
|
"type": {
|
|
"type": "string",
|
|
"enum": ["string", "bool", "number", "color", "length", "font-size", "enum"]
|
|
},
|
|
"description": { "type": "string" },
|
|
"aliases": { "$ref": "#/$defs/aliases" },
|
|
"values": {
|
|
"type": "array",
|
|
"items": { "type": "string" },
|
|
"description": "for type=enum, the allowed canonical values"
|
|
},
|
|
"modifiers": {
|
|
"type": "object",
|
|
"description": "for enum-like properties with orthogonal modifiers (e.g. chartType + 3d/stacked). Each modifier declares how it composes into the final value and which base values it applies to.",
|
|
"additionalProperties": {
|
|
"type": "object",
|
|
"properties": {
|
|
"prefix": { "type": "string", "description": "modifier composed as '<prefix><Base>', e.g. stackedBar" },
|
|
"suffix": { "type": "string", "description": "modifier composed as '<base><suffix>', e.g. column3d" },
|
|
"example": { "type": "string" },
|
|
"appliesWhen": { "$ref": "#/$defs/appliesWhen" }
|
|
},
|
|
"additionalProperties": false
|
|
}
|
|
},
|
|
"appliesWhen": { "$ref": "#/$defs/appliesWhen" },
|
|
"requires": {
|
|
"type": "array",
|
|
"items": { "type": "string" },
|
|
"description": "other properties on the same element that must be set together with this one for the OOXML result to be well-formed (e.g. opacity requires fill to attach alpha to). Contract tests automatically bundle `requires` entries."
|
|
},
|
|
"add": { "type": "boolean" },
|
|
"set": { "type": "boolean" },
|
|
"get": { "type": "boolean" },
|
|
"examples": { "type": "array", "items": { "type": "string" } },
|
|
"readback": {
|
|
"type": "string",
|
|
"description": "expected format of the Get readback value"
|
|
},
|
|
"enforcement": {
|
|
"type": "string",
|
|
"enum": ["strict", "report"],
|
|
"description": "strict = contract test failure breaks CI; report = drift only logged. New properties default to strict; historical debt may start as report and migrate."
|
|
}
|
|
},
|
|
"additionalProperties": false
|
|
},
|
|
"childRef": {
|
|
"type": "object",
|
|
"required": ["element", "pathSegment", "cardinality"],
|
|
"properties": {
|
|
"element": { "type": "string", "description": "name of the child element's schema file (without .json)" },
|
|
"pathSegment": { "type": "string", "description": "CLI path segment for this child, e.g. 'series', 'title', 'axis'" },
|
|
"cardinality": {
|
|
"type": "string",
|
|
"enum": ["0..1", "1", "0..n", "1..n"],
|
|
"description": "0..1 = singleton optional (no [N]); 1 = singleton required; 0..n / 1..n = indexed or keyed"
|
|
},
|
|
"key": {
|
|
"type": "string",
|
|
"description": "if children are addressed by attribute instead of [N], name of that attribute (e.g. 'role' for axis[@role=value])"
|
|
},
|
|
"keyValues": { "type": "array", "items": { "type": "string" }, "description": "permitted values for the key attribute" },
|
|
"appliesWhen": { "$ref": "#/$defs/appliesWhen" }
|
|
},
|
|
"additionalProperties": false
|
|
}
|
|
}
|
|
}
|