@openpresentation/opf 0.11.3 → 0.12.0

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

@@ -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."
@@ -532,7 +543,7 @@
         },
         "logo": {
           "$ref": "#/$defs/Asset",
-          "description": "Source for the organization's logo image. Accepts an HTTPS URL, data URI, relative path (resolved against the OPF file location), local path, or 'asset:<id>' reference. Common formats are SVG (preferred for vector logos), PNG (with transparency), or JPG. The primary organization's logo is used by default for cover-slide and footer branding; design.logo overrides the source.",
+          "description": "Source for the organization's logo image. Accepts an HTTPS URL, data URI, relative path (resolved against the OPF file location), local path, or 'asset:<id>' reference. Common formats are SVG (preferred for vector logos), PNG (with transparency), or JPG. The primary organization's logo (role 'primary', else the first organization) is the fallback source wherever the deck logo is drawn: a slide's design.logo, then design.logo, then this value. It is therefore drawn on cover and section slides and by header/footer zones with logo: true, exactly as design.logo would be (see design.logo and docs/design-resolution.md).",
           "examples": [
             "https://cdn.acme.com/logo.svg",
             "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAusB9V3iWggAAAAASUVORK5CYII=",
@@ -595,7 +606,7 @@
         },
         "photo": {
           "$ref": "#/$defs/Asset",
-          "description": "Source for the speaker's headshot image. Accepts an HTTPS URL, data URI, relative path (resolved against the OPF file location), local path, or 'asset:<id>' reference. Common formats are JPG or PNG; SVG is not appropriate for photographic content. Used on cover and bio slides.",
+          "description": "Source for the speaker's headshot image. Accepts an HTTPS URL, data URI, relative path (resolved against the OPF file location), local path, or 'asset:<id>' reference. Common formats are JPG or PNG; SVG is not appropriate for photographic content. Authoring metadata for hosts and layouts (cover and bio slides built by a host): the reference renderer and exporter do not draw it, because no slide field or layout slot places a speaker; it round-trips through PPTX provenance.",
           "examples": [
             "https://cdn.acme.com/headshots/alice.jpg",
             "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0aHBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/2wBDAQkJCQwLDBgNDRgyIRwhMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjL/wAARCAABAAEDASIAAhEBAxEB/8QAFQABAQAAAAAAAAAAAAAAAAAAAAr/xAAUEAEAAAAAAAAAAAAAAAAAAAAA/8QAFAEBAAAAAAAAAAAAAAAAAAAAAP/EABQRAQAAAAAAAAAAAAAAAAAAAAD/2gAMAwEAAhEDEQA/AJ//2Q==",
@@ -855,7 +866,7 @@
             { "$ref": "#/$defs/Asset" },
             { "$ref": "#/$defs/LogoSet" }
           ],
-          "description": "Deck logo assets used by layouts, covers, section dividers, headers, and footers. A string is the default logo source; object form provides light/dark, stacked, icon, and wordmark variants. When omitted, the renderer falls back to the primary organization logo.",
+          "description": "Deck logo assets used by covers, section dividers, headers, footers and picture bullets. A string or Asset object is the default logo source; the LogoSet object form provides light/dark, stacked, icon, and wordmark variants (see LogoSet for the selection order). Source precedence: a slide's design.logo, then this value, then the primary organization's logo; absence inherits. Placement (reference engines, vetoable): on a cover or section slide (no body payload on a heading-only layout such as title, title-subtitle or section-divider, or no layout) the lockup variant is drawn at the top-left of the free area, inside the slide padding and below any header furniture, in a box 56 reference pixels tall and at most four times as wide; the tag/title/subtitle group then centers in the remaining span. Content slides never get an automatic logo. Header and footer zones draw the icon variant when they set logo: true, and design.listBullet 'image' draws it as the picture bullet. composeSlide returns the cover box as geometry.logo.",
           "examples": [
             "asset:acme-logo",
             { "default": "asset:acme-logo", "light": "asset:acme-logo-white", "icon": "asset:acme-icon" }
@@ -1008,12 +1019,12 @@
         "contentDirection": {
           "type": "string",
           "enum": ["horizontal", "vertical"],
-          "description": "Axis along which parallel body/content regions are arranged."
+          "description": "Axis along which parallel body content is arranged. Sets the root arrangement mode of blocks and root payloads when no composition.mode is set on the slide or on its layout record: 'vertical' is column, 'horizontal' is row. Precedence: composition.mode (the slide's own, else the layout record's geometry contract), then this value (slide design, then deck design), then the layout record's slideLayoutDirection, then automatic selection. A layout that carries a composition.mode keeps its grid or direction whatever this value says. Promoted regions (left, top:left, ...) keep their explicit geometry and nested groups keep their own composition."
         },
         "chartPrimary": {
           "type": "string",
           "enum": ["none", "top", "bottom", "left", "right"],
-          "description": "For chart layouts, where the primary chart sits relative to supporting content. 'none' means chart regions have equal weight."
+          "description": "Where the primary chart sits relative to supporting content. Effective value: slide design, then deck design, then the layout record's contentTypeChartPrimary. When the slide has no promoted regions and no composition.mode of its own, and its root nodes mix at least one chart with other content, the first chart becomes a primary track and the other nodes form one synthetic sub-grid: 'left'/'right' is a two-track row and 'top'/'bottom' a two-track column, weighted 3:2 in favor of the chart; explicit root columns and weights are ignored while it applies. 'none' (the default) keeps the ordinary automatic grid with equal weight."
         },
         "imageFill": {
           "type": "string",
@@ -1023,7 +1034,7 @@
         "listBullet": {
           "type": "string",
           "enum": ["character", "image"],
-          "description": "Default bullet rendering style for list layouts."
+          "description": "Marker style for items and bullets lists. 'character' (the default) draws the glyph marker. 'image' draws the deck's icon logo (a slide's design.logo, then design.logo, then the primary organization's logo; light variants on dark backgrounds) as a picture bullet: a square of the marker's font size whose bottom sits on the marker baseline, so list geometry does not change. Without a logo the glyph is drawn and the engine reports unresolved-content at this field."
         }
       }
     },
@@ -1280,7 +1291,7 @@
         },
         "accent": {
           "$ref": "#/$defs/Font",
-          "description": "Abstract role: font used for accent text such as quotes or callouts. No direct OOXML slot."
+          "description": "Abstract role: font used for accent text. When set, the slide tag (eyebrow) and the quote body use this family instead of the body and heading families; nothing else changes. resolveFontFamilies() returns it as accent only when the scheme defines it. No direct OOXML slot: PPTX export writes it on those runs, and the theme fonts stay major/minor."
         },
         "code": {
           "$ref": "#/$defs/Font",
@@ -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"
+      ],
+      "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"
       ],
-      "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": "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": [
@@ -1450,7 +1810,7 @@
         },
         "color": {
           "type": "string",
-          "description": "Fixed solid fill color, usually a hex string. Use { type: 'theme', slot: ... } for PowerPoint's four theme-controlled background choices.",
+          "description": "Fixed solid fill color: a hex string, a color-scheme slot or role name, or a var:<id> variable reference (a ColorRef, resolved against the effective color scheme and the deck variables). Use { type: 'theme', slot: ... } for PowerPoint's four theme-controlled background choices.",
           "examples": ["#FFFFFF", "#0F172A", "#F8FAFC"]
         },
         "opacity": {
@@ -1489,7 +1849,7 @@
                 "properties": {
                   "color": {
                     "type": "string",
-                    "description": "Stop color as a hex string.",
+                    "description": "Stop color: a hex string, a color-scheme slot or role name, or a var:<id> variable reference (a ColorRef).",
                     "examples": ["#1E40AF", "#22D3EE"]
                   },
                   "position": {
@@ -1573,12 +1933,12 @@
             },
             "foregroundColor": {
               "type": "string",
-              "description": "Foreground color for the pattern, usually a hex string.",
+              "description": "Foreground color for the pattern: a hex string, a color-scheme slot or role name, or a var:<id> variable reference (a ColorRef).",
               "examples": ["#0F172A"]
             },
             "backgroundColor": {
               "type": "string",
-              "description": "Background color behind the pattern, usually a hex string.",
+              "description": "Background color behind the pattern: a hex string, a color-scheme slot or role name, or a var:<id> variable reference (a ColorRef).",
               "examples": ["#FFFFFF"]
             }
           }
@@ -1593,7 +1953,7 @@
     },
     "LogoSet": {
       "type": "object",
-      "description": "Deck logo variants surfaced by layouts, covers, section dividers, headers, and footers. Organization identity lives in organization; this object only controls visual rendering assets. Renderer convention: on dark backgrounds prefer the 'light' variant, on light backgrounds prefer the 'dark' variant, and in square/vertical slots prefer the stacked family when present.",
+      "description": "Deck logo variants surfaced by covers, section dividers, headers, footers and picture bullets. Organization identity lives in organization; this object only controls visual rendering assets. Engines select one variant per slot and background tone (resolveLogo in @openpresentation/opf): same-tone variants first, neutral ones next, the opposite tone last. Lockup on a dark background: light, default, stackedLight, stacked, wordmarkLight, wordmark, iconLight, icon, then dark, stackedDark, wordmarkDark, iconDark; on a light background: dark, default, stackedDark, stacked, wordmarkDark, wordmark, iconDark, icon, then light, stackedLight, wordmarkLight, iconLight. The icon slot (headers, footers, picture bullets) tries iconLight or iconDark for the tone, then icon, then the lockup chain; the stacked slot tries stackedLight or stackedDark, then stacked, then the lockup chain.",
       "additionalProperties": false,
       "properties": {
         "default": {
@@ -1684,8 +2044,12 @@
     },
     "HeaderFooterItem": {
       "type": "object",
-      "description": "One header/footer zone. Every configured field renders; fields in one zone stack top to bottom in the order image, text, organization, section, slide number, date. Put a date and a slide number in different zones to keep each on the zone's single line.",
+      "description": "One header/footer zone. Every configured field renders; fields in one zone stack top to bottom in the order logo, image, text, organization, socials, section, slide number, date. Put a date and a slide number in different zones to keep each on the zone's single line.",
       "properties": {
+        "logo": {
+          "type": "boolean",
+          "description": "Whether to render the deck's icon logo in this zone: a slide's design.logo, then design.logo, then the primary organization's logo (LogoSet icon variants first, light ones on dark backgrounds). It is a generated image part in the same box as image; without a logo the engine reports unresolved-content at this field. Use image for a literal picture that is not the deck logo."
+        },
         "text": {
           "type": "string",
           "description": "Literal text rendered in this zone.",
@@ -1799,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'."
@@ -1841,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" },
@@ -2074,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.",
@@ -2167,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,
@@ -2564,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."
             }
           }
         }
@@ -2603,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": [
@@ -2664,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.",
@@ -2689,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": [", ", "; "]
         }
       }
     },