@openpresentation/opf 0.11.4 → 0.12.1

package/dist/spec/schemas/opf.schema.json

@@ -75,15 +75,15 @@
           "minItems": 1
         }
       ],
-      "description": "Intended audiences for the presentation. Accepts either:\n- A single string shorthand: free-form description ('Series B investors'), an audiences catalog id ('executives'), an HTTPS URL, or a 'pkg:' reference.\n- An array of string shorthands and/or inline Audience objects for custom audience metadata or catalog-backed overrides. Object form mirrors https://openpresentation.org/schema/opf-audience/v1 without '$schema'.\n\nResolution order for catalog ids and references: inline catalogs.audiences.records[] → catalogs.audiences.source → default catalog at https://www.pptx.gallery/audiences.",
+      "description": "Intended audiences for the presentation. Accepts either:\n- A single string shorthand: free-form description ('Series B investors'), an audiences catalog id ('executive'), an HTTPS URL, or a 'pkg:' reference.\n- An array of string shorthands and/or inline Audience objects for custom audience metadata or catalog-backed overrides. Object form mirrors https://openpresentation.org/schema/opf-audience/v1 without '$schema'.\n\nResolution order for catalog ids and references: inline catalogs.audiences.records[] → catalogs.audiences.source → default catalog at https://www.pptx.gallery/audiences.",
       "examples": [
-        "executives",
+        "executive",
         "Biology Students and Wildlife Enthusiasts",
-        ["executives"],
+        ["executive"],
         ["board", "c-suite"],
         ["Series B investors", "https://acme.com/decks/audiences/acme-board.json"],
         [
-          { "id": "executives", "attentionBudgetMinutes": 20 },
+          { "id": "executive", "attentionBudgetMinutes": 20 },
           { "name": "Regional Sales Leaders", "seniority": "director", "technicalFluency": "medium", "decisionPower": "advisory" }
         ]
       ]
@@ -178,7 +178,12 @@
     },
     "variables": {
       "$ref": "#/$defs/Variables",
-      "description": "Optional named color variables for values the deck uses in more than one place or wants to name for intent (e.g. a risk red, a brand highlight). Content color fields reference entries as 'var:<id>' strings. Variables complement the color scheme: scheme slots and roles stay the primary vocabulary; variables cover deck-specific named colors that have no scheme slot."
+      "description": "Optional named variables: deck colors referenced as 'var:<id>' (the original use), and typed content variables (text, number, date, image, url, list) referenced inline as '{{<id>}}' or whole as 'var:<id>'. Variables are what makes a deck a fillable template when combined with 'template': true. Color variables complement the color scheme: scheme slots and roles stay the primary vocabulary; variables cover deck-specific named colors that have no scheme slot."
+    },
+    "template": {
+      "type": "boolean",
+      "description": "Marks this document as a template: an incomplete OPF file. A template declares variables (top-level 'variables') and references them from content, and may leave required variables unfilled; validation then reports the unfilled variables instead of failing, and previews and exports use each variable's 'example'. Filling a template (resolveVariables, or 'opf fill') returns a normal deck with this marker removed. Absent or false: a normal deck, where an unfilled required variable is an error. See docs/templates-and-variables.md.",
+      "default": false
     },
     "narrative": {
       "oneOf": [
@@ -202,6 +207,12 @@
       "minItems": 1,
       "description": "Ordered array of slides that make up the presentation."
     },
+    "references": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/Reference" },
+      "description": "Sources that text runs cite with 'cite'. Ids are unique. A cited reference is listed in the footnote area of every slide that cites it, with a marker number assigned per deck in order of first use; a reference no run cites is a lint warning (opf/unused-reference). referencesSlide() turns the cited references into an ordinary list slide.",
+      "examples": [[{ "id": "gartner-2026", "text": "Gartner, Market Guide for Presentation Tooling, 2026", "url": "https://www.gartner.com" }]]
+    },
     "assets": {
       "$ref": "#/$defs/Assets",
       "description": "Optional reusable asset registry for images, data files, videos, documents, fonts, and other resources referenced elsewhere in the deck via 'asset:<id>' strings."
@@ -286,7 +297,7 @@
           "type": "string",
           "pattern": "^[a-z][a-z0-9-]*$",
           "description": "Optional audiences catalog id to resolve before applying inline overrides.",
-          "examples": ["executives", "board", "engineering-team"]
+          "examples": ["executive", "board", "engineering-team"]
         },
         "name": {
           "type": "string",
@@ -686,7 +697,7 @@
           "type": "array",
           "items": { "type": "string" },
           "description": "Audiences this narrative works well for. Free-form strings or 'audiences' catalog ids.",
-          "examples": [["executives", "investors", "customers"]]
+          "examples": [["executive", "investor", "customer"]]
         },
         "durationRange": {
           "type": "object",
@@ -1372,38 +1383,387 @@
       "propertyNames": {
         "pattern": "^[a-z][a-z0-9-]*$"
       },
-      "additionalProperties": { "$ref": "#/$defs/Variable" },
-      "description": "Named color variables, keyed by stable kebab-case id. Content color fields reference entries as 'var:<id>' strings. Each value is a hex string shorthand or a Variable object.",
+      "additionalProperties": {
+        "$ref": "#/$defs/Variable"
+      },
+      "description": "Named variables, keyed by stable kebab-case id. A variable is a typed, named value the deck declares once and uses in many places: a color ('var:<id>' in color fields, the original use), or content that fills a template (text, number, date, image, url, list). Content is referenced inline as '{{<id>}}' inside any string, or whole as 'var:<id>' in a field of the matching type; '\\{{' writes a literal '{{'. A hex string is shorthand for a color variable. A variable with no 'value' is unfilled: expected in a template (root 'template': true), an error in a normal deck. Engines resolve variables with resolveVariables() before composing, rendering or exporting, so a template plus its values previews and exports exactly like the equivalent hand-written deck. See docs/templates-and-variables.md.",
       "examples": [
-        { "risk": "#B42318", "highlight": { "type": "color", "value": "#0F4C81", "description": "Brand highlight for emphasized runs." } }
+        {
+          "risk": "#B42318",
+          "highlight": {
+            "type": "color",
+            "value": "#0F4C81",
+            "description": "Brand highlight for emphasized runs."
+          }
+        },
+        {
+          "client-name": {
+            "type": "text",
+            "example": "Acme Corp",
+            "description": "Customer the deck is for."
+          },
+          "revenue": {
+            "type": "number",
+            "example": 1250000,
+            "format": "$#,##0"
+          },
+          "review-date": {
+            "type": "date",
+            "example": "2026-10-01"
+          }
+        }
       ]
     },
     "Variable": {
       "oneOf": [
-        { "$ref": "#/$defs/HexColor" },
         {
-          "type": "object",
-          "required": ["type", "value"],
-          "additionalProperties": false,
-          "properties": {
-            "type": {
-              "type": "string",
-              "enum": ["color"],
-              "description": "Variable kind. Only 'color' is defined today; other kinds may be added when content surfaces exist to consume them."
+          "$ref": "#/$defs/HexColor"
+        },
+        {
+          "$ref": "#/$defs/ColorVariable"
+        },
+        {
+          "$ref": "#/$defs/TextVariable"
+        },
+        {
+          "$ref": "#/$defs/NumberVariable"
+        },
+        {
+          "$ref": "#/$defs/DateVariable"
+        },
+        {
+          "$ref": "#/$defs/ImageVariable"
+        },
+        {
+          "$ref": "#/$defs/UrlVariable"
+        },
+        {
+          "$ref": "#/$defs/ListVariable"
+        }
+      ],
+      "description": "A single named variable: a hex string (shorthand for a color variable) or an object whose 'type' is color, text, number, date, image, url or list. 'value' is the current value and is optional: a variable with no value is unfilled, which a template allows and a normal deck does not. 'example' only illustrates the slot (fill forms, template previews) and never reaches output.",
+      "examples": [
+        "#B42318",
+        {
+          "type": "color",
+          "value": "#B42318",
+          "description": "Risk emphasis."
+        },
+        {
+          "type": "text",
+          "example": "Acme Corp"
+        },
+        {
+          "type": "list",
+          "value": [
+            "Faster",
+            "Cheaper"
+          ]
+        }
+      ]
+    },
+    "ColorVariable": {
+      "type": "object",
+      "required": [
+        "type"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "type": {
+          "type": "string",
+          "const": "color",
+          "description": "Variable kind. One of color, text, number, date, image, url or list."
+        },
+        "value": {
+          "$ref": "#/$defs/HexColor",
+          "description": "Hex color this variable resolves to."
+        },
+        "required": {
+          "type": "boolean",
+          "default": true,
+          "description": "Whether the variable must be filled. Defaults to true: a variable with no 'value' is unfilled, and an unfilled required variable is an error in a normal deck and expected in a template. Set false for an optional slot: an unfilled optional variable resolves to empty text (inline tokens) or the field that references it is omitted."
+        },
+        "label": {
+          "type": "string",
+          "description": "Optional short human label for forms and fill panels."
+        },
+        "description": {
+          "type": "string",
+          "description": "Optional prose describing what the variable is for, surfaced by pickers, fill forms and agents."
+        },
+        "example": {
+          "$ref": "#/$defs/HexColor",
+          "description": "Illustrative color shown in fill forms and used when a template is previewed with examples. Never written to output."
+        }
+      },
+      "description": "A named color. Content color fields reference it as 'var:<id>'. Colors resolve at render time through the ordinary color-reference path, so a color variable keeps working as before."
+    },
+    "TextVariable": {
+      "type": "object",
+      "required": [
+        "type"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "type": {
+          "type": "string",
+          "const": "text",
+          "description": "Variable kind. One of color, text, number, date, image, url or list."
+        },
+        "value": {
+          "oneOf": [
+            {
+              "type": "string"
             },
-            "value": {
-              "$ref": "#/$defs/HexColor",
-              "description": "Hex color this variable resolves to."
+            {
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/TextRun"
+              }
+            }
+          ],
+          "description": "Text this variable resolves to: a plain string, or TextRun[] for rich text."
+        },
+        "required": {
+          "type": "boolean",
+          "default": true,
+          "description": "Whether the variable must be filled. Defaults to true: a variable with no 'value' is unfilled, and an unfilled required variable is an error in a normal deck and expected in a template. Set false for an optional slot: an unfilled optional variable resolves to empty text (inline tokens) or the field that references it is omitted."
+        },
+        "label": {
+          "type": "string",
+          "description": "Optional short human label for forms and fill panels."
+        },
+        "description": {
+          "type": "string",
+          "description": "Optional prose describing what the variable is for, surfaced by pickers, fill forms and agents."
+        },
+        "example": {
+          "oneOf": [
+            {
+              "type": "string"
             },
-            "description": {
-              "type": "string",
-              "description": "Optional prose describing what the variable is for, surfaced by pickers and agents."
+            {
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/TextRun"
+              }
             }
-          }
+          ],
+          "description": "Illustrative text shown in fill forms and used when a template is previewed with examples. Never written to output."
+        }
+      },
+      "description": "Text content. Plain string or rich TextRun[]. Insert it inline as '{{<id>}}' inside any string (rich text is flattened to plain text there), or reference it whole as 'var:<id>' in a field that accepts string or TextRun[] (the rich runs are kept)."
+    },
+    "NumberVariable": {
+      "type": "object",
+      "required": [
+        "type"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "type": {
+          "type": "string",
+          "const": "number",
+          "description": "Variable kind. One of color, text, number, date, image, url or list."
+        },
+        "value": {
+          "type": "number",
+          "description": "Number this variable resolves to."
+        },
+        "required": {
+          "type": "boolean",
+          "default": true,
+          "description": "Whether the variable must be filled. Defaults to true: a variable with no 'value' is unfilled, and an unfilled required variable is an error in a normal deck and expected in a template. Set false for an optional slot: an unfilled optional variable resolves to empty text (inline tokens) or the field that references it is omitted."
+        },
+        "label": {
+          "type": "string",
+          "description": "Optional short human label for forms and fill panels."
+        },
+        "description": {
+          "type": "string",
+          "description": "Optional prose describing what the variable is for, surfaced by pickers, fill forms and agents."
+        },
+        "example": {
+          "type": "number",
+          "description": "Illustrative number shown in fill forms and used when a template is previewed with examples. Never written to output."
+        },
+        "format": {
+          "type": "string",
+          "description": "Display pattern used by '{{<id>}}'. A literal prefix, a numeric part of '#', '0', ',' and '.', and a literal suffix. '0' pads digits, '#' is optional, ',' groups thousands, digits after '.' fix the decimals ('0' required, '#' optional), and a '%' in the suffix scales by 100. English separators only. Absent: the shortest decimal form.",
+          "examples": [
+            "#,##0",
+            "0.0",
+            "$#,##0.00",
+            "0.#%",
+            "#,##0.0M"
+          ]
         }
+      },
+      "description": "A number. '{{<id>}}' inserts it as text using 'format'; 'var:<id>' as a whole field supplies the number itself (chart values, font sizes)."
+    },
+    "DateVariable": {
+      "type": "object",
+      "required": [
+        "type"
       ],
-      "description": "A single named variable. A hex string is shorthand for { \"type\": \"color\", \"value\": value }.",
-      "examples": ["#B42318", { "type": "color", "value": "#B42318", "description": "Risk emphasis." }]
+      "additionalProperties": false,
+      "properties": {
+        "type": {
+          "type": "string",
+          "const": "date",
+          "description": "Variable kind. One of color, text, number, date, image, url or list."
+        },
+        "value": {
+          "type": "string",
+          "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+          "description": "ISO calendar date (YYYY-MM-DD) this variable resolves to."
+        },
+        "required": {
+          "type": "boolean",
+          "default": true,
+          "description": "Whether the variable must be filled. Defaults to true: a variable with no 'value' is unfilled, and an unfilled required variable is an error in a normal deck and expected in a template. Set false for an optional slot: an unfilled optional variable resolves to empty text (inline tokens) or the field that references it is omitted."
+        },
+        "label": {
+          "type": "string",
+          "description": "Optional short human label for forms and fill panels."
+        },
+        "description": {
+          "type": "string",
+          "description": "Optional prose describing what the variable is for, surfaced by pickers, fill forms and agents."
+        },
+        "example": {
+          "type": "string",
+          "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+          "description": "Illustrative ISO date shown in fill forms and used when a template is previewed with examples. Never written to output."
+        },
+        "format": {
+          "type": "string",
+          "description": "Date display pattern, the same LDML-style tokens as header/footer dateFormat: yyyy, yy, MMMM, MMM, MM, M, dd, d, EEEE, EEE and quoted literals. English names. Default 'MMMM d, yyyy'.",
+          "examples": [
+            "MMMM d, yyyy",
+            "dd MMM yyyy",
+            "M/d/yyyy",
+            "EEEE, MMMM d"
+          ]
+        }
+      },
+      "description": "A calendar date as an ISO YYYY-MM-DD string. No time zone and no clock are involved. '{{<id>}}' inserts it formatted with 'format'."
+    },
+    "ImageVariable": {
+      "type": "object",
+      "required": [
+        "type"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "type": {
+          "type": "string",
+          "const": "image",
+          "description": "Variable kind. One of color, text, number, date, image, url or list."
+        },
+        "value": {
+          "$ref": "#/$defs/Asset",
+          "description": "Image source this variable resolves to."
+        },
+        "required": {
+          "type": "boolean",
+          "default": true,
+          "description": "Whether the variable must be filled. Defaults to true: a variable with no 'value' is unfilled, and an unfilled required variable is an error in a normal deck and expected in a template. Set false for an optional slot: an unfilled optional variable resolves to empty text (inline tokens) or the field that references it is omitted."
+        },
+        "label": {
+          "type": "string",
+          "description": "Optional short human label for forms and fill panels."
+        },
+        "description": {
+          "type": "string",
+          "description": "Optional prose describing what the variable is for, surfaced by pickers, fill forms and agents."
+        },
+        "example": {
+          "$ref": "#/$defs/Asset",
+          "description": "Illustrative image source shown in fill forms and used when a template is previewed with examples. Never written to output."
+        }
+      },
+      "description": "An image source: any Asset (an 'asset:<id>' reference, HTTPS URL, data URI, relative or local path, or an object with src, alt and metadata). Reference it whole as 'var:<id>' in an image, asset or src field; '{{<id>}}' inserts the source string."
+    },
+    "UrlVariable": {
+      "type": "object",
+      "required": [
+        "type"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "type": {
+          "type": "string",
+          "const": "url",
+          "description": "Variable kind. One of color, text, number, date, image, url or list."
+        },
+        "value": {
+          "type": "string",
+          "pattern": "^(?:https?://|mailto:|tel:)\\S+$",
+          "description": "Link target this variable resolves to."
+        },
+        "required": {
+          "type": "boolean",
+          "default": true,
+          "description": "Whether the variable must be filled. Defaults to true: a variable with no 'value' is unfilled, and an unfilled required variable is an error in a normal deck and expected in a template. Set false for an optional slot: an unfilled optional variable resolves to empty text (inline tokens) or the field that references it is omitted."
+        },
+        "label": {
+          "type": "string",
+          "description": "Optional short human label for forms and fill panels."
+        },
+        "description": {
+          "type": "string",
+          "description": "Optional prose describing what the variable is for, surfaced by pickers, fill forms and agents."
+        },
+        "example": {
+          "type": "string",
+          "pattern": "^(?:https?://|mailto:|tel:)\\S+$",
+          "description": "Illustrative link shown in fill forms and used when a template is previewed with examples. Never written to output."
+        }
+      },
+      "description": "A link target (http, https, mailto or tel). Use it as '{{<id>}}' inside a link string or reference it whole as 'var:<id>' in a link field."
+    },
+    "ListVariable": {
+      "type": "object",
+      "required": [
+        "type"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "type": {
+          "type": "string",
+          "const": "list",
+          "description": "Variable kind. One of color, text, number, date, image, url or list."
+        },
+        "value": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Entries this variable resolves to."
+        },
+        "required": {
+          "type": "boolean",
+          "default": true,
+          "description": "Whether the variable must be filled. Defaults to true: a variable with no 'value' is unfilled, and an unfilled required variable is an error in a normal deck and expected in a template. Set false for an optional slot: an unfilled optional variable resolves to empty text (inline tokens) or the field that references it is omitted."
+        },
+        "label": {
+          "type": "string",
+          "description": "Optional short human label for forms and fill panels."
+        },
+        "description": {
+          "type": "string",
+          "description": "Optional prose describing what the variable is for, surfaced by pickers, fill forms and agents."
+        },
+        "example": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Illustrative entries shown in fill forms and used when a template is previewed with examples. Never written to output."
+        }
+      },
+      "description": "A list of strings, for bullets and list items. A whole-string array element 'var:<id>' splices every entry into the array in place; a whole field 'var:<id>' becomes the array; '{{<id>}}' joins the entries with ', ' (or the separator after a pipe: '{{<id>|; }}')."
     },
     "BackgroundShortcut": {
       "oneOf": [
@@ -1803,6 +2163,11 @@
           "items": { "$ref": "#/$defs/BulletItem" },
           "description": "Full-slide text-style bullet payload. Presence of this field infers type 'text'."
         },
+        "numbering": {
+          "$ref": "#/$defs/NumberingSpec",
+          "description": "Number the full-slide `items` or `bullets` instead of bulleting them. A style name (arabic, roman-upper, roman-lower, alpha-upper, alpha-lower) or a Numbering object applies to every list level; an array gives one entry per level (index = level, the last entry repeats for deeper levels). Counting follows PowerPoint: consecutive entries of one level count up from its start, and an entry of a shallower level restarts the deeper levels. Absent = bullets. Valid only with `items` or `bullets`. Native PowerPoint export writes a:buAutoNum with the matching scheme and startAt; the preview draws the same numbers at the same marker geometry.",
+          "examples": ["arabic", "roman-lower", { "style": "alpha-upper", "start": 3, "suffix": "paren" }, ["arabic", "alpha-lower", { "style": "roman-lower", "suffix": "paren-both" }]]
+        },
         "image": {
           "$ref": "#/$defs/Asset",
           "description": "Full-slide image source. Presence of this field infers type 'image'."
@@ -1845,6 +2210,10 @@
           "$ref": "#/$defs/Timeline",
           "description": "Full-slide timeline payload. An array is shorthand for { \"events\": value }; object form carries optional name and description metadata. Presence of this field infers type 'timeline'."
         },
+        "caption": {
+          "$ref": "#/$defs/Caption",
+          "description": "Caption for the slide's root image, chart, table or video payload. Valid only when the slide root holds exactly one of those payloads."
+        },
         "blocks": {
           "type": "array",
           "items": { "$ref": "#/$defs/ContentPayload" },
@@ -2078,6 +2447,11 @@
           "description": "Text-style bullet payload. Presence of this field infers type 'text'.",
           "examples": [["Sub-second agent latency", "Drop-in compatible with OpenAI tool-calling", "SOC 2 Type II"]]
         },
+        "numbering": {
+          "$ref": "#/$defs/NumberingSpec",
+          "description": "Number the payload's `items` or `bullets` instead of bulleting them. A style name (arabic, roman-upper, roman-lower, alpha-upper, alpha-lower) or a Numbering object applies to every list level; an array gives one entry per level (index = level, the last entry repeats for deeper levels). Counting follows PowerPoint: consecutive entries of one level count up from its start, and an entry of a shallower level restarts the deeper levels. Absent = bullets. Valid only with `items` or `bullets`. Native PowerPoint export writes a:buAutoNum with the matching scheme and startAt; the preview draws the same numbers at the same marker geometry.",
+          "examples": ["arabic", "roman-lower", { "style": "alpha-upper", "start": 3, "suffix": "paren" }, ["arabic", "alpha-lower", { "style": "roman-lower", "suffix": "paren-both" }]]
+        },
         "image": {
           "$ref": "#/$defs/Asset",
           "description": "Source for an image item.",
@@ -2171,6 +2545,10 @@
             }
           ]
         },
+        "caption": {
+          "$ref": "#/$defs/Caption",
+          "description": "Caption for an image, chart, table or video payload, composed inside the block's region (below the media by default). Invalid on other payload kinds and on groups."
+        },
         "blocks": {
           "type": "array",
           "minItems": 1,
@@ -2568,6 +2946,12 @@
               "type": "integer",
               "minimum": 0,
               "description": "Zero-based nesting level for the list item."
+            },
+            "start": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 32767,
+              "description": "Restart the list's numbering at this number for this item (counted at its level); the entries after it continue from it. Only meaningful when the payload has `numbering`. Paginated continuation pages use it to keep the numbers of the whole list."
             }
           }
         }
@@ -2607,11 +2991,62 @@
               "type": "integer",
               "minimum": 0,
               "description": "Zero-based nesting level for the bullet."
+            },
+            "start": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 32767,
+              "description": "Restart the list's numbering at this number for this bullet (counted at its level); the entries after it continue from it. Only meaningful when the payload has `numbering`. Paginated continuation pages use it to keep the numbers of the whole list."
             }
           }
         }
       ]
     },
+    "NumberingStyle": {
+      "type": "string",
+      "enum": ["arabic", "roman-upper", "roman-lower", "alpha-upper", "alpha-lower"],
+      "description": "A list number style: 1, 2, 3; I, II, III; i, ii, iii; A, B, C; a, b, c. Alphabetic numbering past 26 repeats the letter as PowerPoint does (aa, bb, cc). Roman numerals stop at 3999; larger values are drawn in arabic with a numbering-adapted diagnostic."
+    },
+    "Numbering": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Numbering of one list level.",
+      "properties": {
+        "style": {
+          "$ref": "#/$defs/NumberingStyle",
+          "description": "Number style. Default arabic."
+        },
+        "start": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 32767,
+          "description": "First number counted at this level. Default 1. Native PowerPoint accepts 1 to 32767."
+        },
+        "suffix": {
+          "type": "string",
+          "enum": ["period", "paren", "paren-both"],
+          "description": "Text after the number: period (1.), paren (1)) or paren-both ((1)). Default period."
+        }
+      }
+    },
+    "NumberingSpec": {
+      "description": "The value of a numbering field: a style name or Numbering object for every level, or an array with one entry per level (at most 9, the native depth).",
+      "oneOf": [
+        { "$ref": "#/$defs/NumberingStyle" },
+        { "$ref": "#/$defs/Numbering" },
+        {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 9,
+          "items": {
+            "oneOf": [
+              { "$ref": "#/$defs/NumberingStyle" },
+              { "$ref": "#/$defs/Numbering" }
+            ]
+          }
+        }
+      ]
+    },
     "TextRun": {
       "description": "A contiguous run of text. Strings cover unformatted spans; object form adds character formatting.",
       "oneOf": [
@@ -2668,11 +3103,88 @@
             "subscript": {
               "type": "boolean",
               "description": "Whether the run is rendered as subscript."
+            },
+            "cite": {
+              "oneOf": [
+                { "type": "string", "minLength": 1 },
+                { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } }
+              ],
+              "description": "One or more ids from the top-level references list that this run cites. Engines draw a superscript marker ('1', or '1,2' for several ids) directly after the run and list '<n> <reference text>' in the slide's footnote area; markers are numbered per deck in order of first use, and the same id keeps its number. An id missing from references is a validation error (cite-unknown-reference). Supported in text, bullets and list item runs.",
+              "examples": ["gartner-2026", ["gartner-2026", "annual-report"]]
+            },
+            "footnote": {
+              "oneOf": [
+                { "type": "string", "minLength": 1 },
+                { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/TextRun" } }
+              ],
+              "description": "An inline note for this run, without a references entry. Engines draw a superscript marker after the run and list the note in the slide's footnote area; every footnote takes a new number in the deck's marker sequence. Supported in text, bullets and list item runs.",
+              "examples": ["Excludes the discontinued hardware line."]
+            }
+          }
+        }
+      ]
+    },
+    "Caption": {
+      "description": "A caption for an image, chart, table or video payload. A string or TextRun[] is the caption text placed below the media; object form adds the position and alignment.",
+      "oneOf": [
+        { "type": "string" },
+        { "type": "array", "items": { "$ref": "#/$defs/TextRun" } },
+        {
+          "type": "object",
+          "required": ["text"],
+          "additionalProperties": false,
+          "properties": {
+            "text": {
+              "oneOf": [
+                { "type": "string" },
+                { "type": "array", "items": { "$ref": "#/$defs/TextRun" } }
+              ],
+              "description": "Caption text: a string or TextRun[] for inline rich text."
+            },
+            "position": {
+              "type": "string",
+              "enum": ["below", "above"],
+              "description": "Where the caption band sits inside the block's region: below the media (default) or above it. Core composition reserves the band and shrinks the media by its height."
+            },
+            "align": {
+              "type": "string",
+              "enum": ["left", "center", "right"],
+              "description": "Horizontal alignment of the caption text within the block. Defaults to left."
             }
           }
         }
+      ],
+      "examples": [
+        "Figure 1. Quarterly revenue by region",
+        { "text": "Source: internal reporting", "position": "above", "align": "center" }
       ]
     },
+    "Reference": {
+      "type": "object",
+      "description": "A source that runs cite with 'cite'. Cited references are listed in the footnote area of the slides that cite them, numbered per deck in order of first use; referencesSlide() builds an ordinary list slide of them.",
+      "additionalProperties": false,
+      "required": ["id", "text"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Identifier runs cite. Unique within the references list.",
+          "examples": ["gartner-2026", "annual-report"]
+        },
+        "text": {
+          "oneOf": [
+            { "type": "string" },
+            { "type": "array", "items": { "$ref": "#/$defs/TextRun" } }
+          ],
+          "description": "The reference as it is listed: a string or TextRun[] for inline rich text."
+        },
+        "url": {
+          "type": "string",
+          "description": "Optional link for the reference; a references slide links its entry to it.",
+          "examples": ["https://acme.com/reports/2026"]
+        }
+      }
+    },
     "Chart": {
       "type": "object",
       "description": "Chart content. The chart object keeps chart-specific fields together so slides and regions do not expose loose chart fields.",
@@ -2693,6 +3205,63 @@
             { "$ref": "#/$defs/ChartDataSource" }
           ],
           "description": "Chart data. Inline data uses a tabular columns/rows shape; renderers convert rows to chart series internally."
+        },
+        "axisTitles": {
+          "$ref": "#/$defs/ChartAxisTitles",
+          "description": "Optional axis titles. Absent keeps today's untitled axes. Supported on the chart types that have a category/value (or X/Y) axis pair (column, bar, line, area, scatter, and the histogram, pareto, waterfall and box-and-whisker constructs; the funnel construct takes a category title only); a title on a type without that axis (pie, doughnut, radar, treemap, map) is dropped with a 'chart-option-adapted' diagnostic by renderers and exporters."
+        },
+        "legend": {
+          "type": "string",
+          "enum": ["none", "top", "bottom", "left", "right"],
+          "description": "Optional legend position. 'none' hides the legend. Absent keeps today's behaviour exactly (a legend at the right of multi-series charts and of pie and doughnut charts, none for single-series charts). A named position shows the legend there even for a single-series chart. Of the Office 2016 constructs only box-and-whisker takes a legend; histogram, pareto, waterfall, funnel, treemap and map drop the option with a 'chart-option-adapted' diagnostic."
+        },
+        "dataLabels": {
+          "oneOf": [
+            { "type": "boolean" },
+            { "$ref": "#/$defs/ChartDataLabels" }
+          ],
+          "description": "Optional data labels. true shows value labels at each type's default position, false (or absent) shows none, which is today's behaviour. Use the object form for the label content, position and separator."
+        }
+      }
+    },
+    "ChartAxisTitles": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Titles for the two axes of a chart. 'category' is the axis that carries the row labels (the horizontal axis of a column or line chart, the vertical axis of a bar chart, the X axis of a scatter chart); 'value' is the other axis.",
+      "properties": {
+        "category": {
+          "type": "string",
+          "description": "Title of the category (X) axis.",
+          "examples": ["Quarter", "Region"]
+        },
+        "value": {
+          "type": "string",
+          "description": "Title of the value (Y) axis.",
+          "examples": ["Revenue ($M)", "Customers"]
+        }
+      }
+    },
+    "ChartDataLabels": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Data label settings. A label shows the selected content parts in the fixed order category, value, percent, joined by the separator.",
+      "properties": {
+        "content": {
+          "type": "array",
+          "items": { "type": "string", "enum": ["value", "percent", "category"] },
+          "minItems": 1,
+          "uniqueItems": true,
+          "description": "Which parts a label shows. Defaults to ['value']. 'percent' is the share of the total and exists only on pie and doughnut charts; 'category' shows the category name (the X value on a scatter chart). A part a chart type cannot show is dropped with a 'chart-option-adapted' diagnostic."
+        },
+        "position": {
+          "type": "string",
+          "enum": ["auto", "center", "inside-end", "inside-base", "outside-end", "above", "below", "left", "right"],
+          "description": "Where a label sits relative to its mark. 'auto' (the default) is the type's default: outside-end for clustered columns and bars, pie slices and the histogram, pareto and waterfall constructs; center for stacked columns and bars; above for line and scatter points. Clustered columns and bars and the histogram, pareto and waterfall constructs take center, inside-end, inside-base and outside-end; stacked columns and bars take center, inside-end and inside-base; pie takes center, inside-end and outside-end; line and scatter points take above, below, left, right and center. Area, doughnut and radar charts and the funnel and treemap constructs take only 'auto' (the box-and-whisker and map constructs have no data labels). An unsupported position falls back to 'auto' with a 'chart-option-adapted' diagnostic."
+        },
+        "separator": {
+          "type": "string",
+          "description": "Text between the parts of a label that shows more than one. Defaults to ', '.",
+          "examples": [", ", "; "]
         }
       }
     },