@openpresentation/opf 0.13.0 → 0.14.0

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

@@ -0,0 +1,191 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openpresentation.org/schema/opf-finding/v1",
+  "title": "Finding Report",
+  "description": "The report format every OPF tool shares. A finding is one thing a checker found at one place in a presentation: a stable rule id, a severity, a category, a JSON Pointer path, a message, and optionally source positions, the measured numbers behind it and suggested fixes as JSON Patch. `validate` in `@openpresentation/opf`, the Markdown and YAML converters, the editor's Review panel and hosted reviewers such as pptx.dev's AI review all produce this shape, so a host shows and applies findings from any of them the same way. A report lists findings, tells whether any has severity `error` (`valid`) and counts them by severity; `validate` adds `schemaValid`, `checks` and variable fields on top of it. Core's checks are deterministic and run locally; findings from other producers use their own rule-id prefix and say so in `source`.",
+  "type": "object",
+  "required": ["valid", "findings", "counts"],
+  "properties": {
+    "valid": {
+      "type": "boolean",
+      "description": "True when no finding has severity `error`."
+    },
+    "findings": {
+      "type": "array",
+      "description": "Every finding, in report order.",
+      "items": { "$ref": "#/$defs/Finding" }
+    },
+    "counts": {
+      "type": "object",
+      "description": "How many findings each severity has.",
+      "required": ["error", "warning", "info"],
+      "additionalProperties": false,
+      "properties": {
+        "error": { "type": "integer", "minimum": 0 },
+        "warning": { "type": "integer", "minimum": 0 },
+        "info": { "type": "integer", "minimum": 0 }
+      }
+    }
+  },
+  "$defs": {
+    "FindingSeverity": {
+      "type": "string",
+      "enum": ["error", "warning", "info"],
+      "description": "`error` makes a report invalid. `warning` is a problem the author should fix. `info` is advisory."
+    },
+    "FindingCategory": {
+      "description": "What kind of question the finding answers. Core uses `format` (is it well-formed OPF), `references` (does everything it points at resolve), `policy` (host house rules), `accessibility`, `layout` (will it present as authored) and `content` (is anything left unfinished). Other producers may use their own category names, such as `narrative` or `audience-fit`.",
+      "anyOf": [
+        { "type": "string", "enum": ["format", "references", "policy", "accessibility", "layout", "content"] },
+        { "type": "string", "minLength": 1 }
+      ]
+    },
+    "FindingLocation": {
+      "type": "object",
+      "description": "A range in the checked text: UTF-16 offset and length from the start, and the one-based line and column of the start. Present when the finding was produced from text (JSON, Markdown or YAML).",
+      "required": ["offset", "length", "line", "column"],
+      "additionalProperties": false,
+      "properties": {
+        "offset": { "type": "integer", "minimum": 0 },
+        "length": { "type": "integer", "minimum": 0 },
+        "line": { "type": "integer", "minimum": 1 },
+        "column": { "type": "integer", "minimum": 1 }
+      }
+    },
+    "JsonPatchOperation": {
+      "description": "One RFC 6902 JSON Patch operation. Paths are JSON Pointers into the checked presentation.",
+      "oneOf": [
+        {
+          "type": "object",
+          "required": ["op", "path", "value"],
+          "additionalProperties": false,
+          "properties": {
+            "op": { "type": "string", "enum": ["add", "replace", "test"] },
+            "path": { "type": "string" },
+            "value": {}
+          }
+        },
+        {
+          "type": "object",
+          "required": ["op", "path"],
+          "additionalProperties": false,
+          "properties": {
+            "op": { "type": "string", "const": "remove" },
+            "path": { "type": "string" }
+          }
+        },
+        {
+          "type": "object",
+          "required": ["op", "from", "path"],
+          "additionalProperties": false,
+          "properties": {
+            "op": { "type": "string", "enum": ["move", "copy"] },
+            "from": { "type": "string" },
+            "path": { "type": "string" }
+          }
+        }
+      ]
+    },
+    "FindingFocus": {
+      "type": "object",
+      "description": "The field an author has to fill in, for a fix that cannot be written as a patch.",
+      "required": ["path", "field"],
+      "additionalProperties": false,
+      "properties": {
+        "path": { "type": "string", "description": "JSON Pointer of the field to edit." },
+        "field": { "type": "string", "description": "What the field is, such as `alt`, `title`, `text`, `link`, `language` or `fontSize`." },
+        "value": { "type": ["string", "number", "boolean", "null", "array", "object"], "description": "The field's current value, when it has one." }
+      }
+    },
+    "FindingFix": {
+      "type": "object",
+      "description": "A suggested repair. Core never applies it: the host shows it and applies it through its own undoable edit path. A `patch` fix carries JSON Patch operations; a `focus` fix only names the field the author has to fill in.",
+      "required": ["title"],
+      "additionalProperties": false,
+      "properties": {
+        "title": { "type": "string", "minLength": 1, "description": "What applying the fix does, in a few words." },
+        "id": { "type": "string", "description": "Stable id within one finding, such as `focus-alt` or `use-readable-color`." },
+        "kind": { "type": "string", "enum": ["patch", "focus"], "default": "patch", "description": "`patch` fixes carry `patch`; `focus` fixes carry `focus`." },
+        "safe": { "type": "boolean", "description": "True when applying the fix cannot change what the content says or how it looks beyond the repair, such as switching a failing colour to the one the theme chose. False fixes need a deliberate choice." },
+        "patch": {
+          "type": "array",
+          "description": "RFC 6902 JSON Patch operations that apply the fix to the checked presentation.",
+          "items": { "$ref": "#/$defs/JsonPatchOperation" }
+        },
+        "focus": { "$ref": "#/$defs/FindingFocus" }
+      }
+    },
+    "FindingSuggestion": {
+      "type": "object",
+      "description": "A value the author could use instead, such as a catalog record that exists. Suggestions name records actually present in the checked context and never replace authored values silently.",
+      "required": ["value", "label", "origin"],
+      "additionalProperties": false,
+      "properties": {
+        "value": { "type": ["string", "number", "boolean", "null"] },
+        "label": { "type": "string" },
+        "origin": { "type": "string", "description": "Where the suggestion comes from: `schema`, `built-in`, `loaded`, `document` or `contract`." },
+        "definition": { "type": "string", "description": "Where the suggested record or constraint is defined." }
+      }
+    },
+    "ValidationIssue": {
+      "type": "object",
+      "description": "The raw schema or semantic issue behind a finding, kept with every union alternative so a host can inspect the exact constraint.",
+      "required": ["path", "message", "keyword", "schemaPath", "params"],
+      "additionalProperties": false,
+      "properties": {
+        "path": { "type": "string" },
+        "message": { "type": "string" },
+        "keyword": { "type": "string", "description": "The JSON Schema keyword that failed, or `opf` for a rule the schema cannot express." },
+        "schemaPath": { "type": "string" },
+        "params": { "type": "object", "additionalProperties": true }
+      }
+    },
+    "Finding": {
+      "type": "object",
+      "description": "One thing a checker found at one place in a presentation.",
+      "required": ["ruleId", "severity", "category", "path", "message"],
+      "additionalProperties": false,
+      "properties": {
+        "ruleId": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*/[A-Za-z0-9][A-Za-z0-9._-]*$",
+          "description": "Stable `<producer>/<rule>` id, such as `opf/text-contrast` for core or `pptx.dev/narrative-gap` for a hosted reviewer. Ids do not change between releases."
+        },
+        "source": {
+          "type": "string",
+          "description": "The producer: `opf` (the default) for core, or the name of another tool such as `pptx.dev/review`."
+        },
+        "severity": { "$ref": "#/$defs/FindingSeverity" },
+        "category": { "$ref": "#/$defs/FindingCategory" },
+        "path": {
+          "type": "string",
+          "description": "JSON Pointer to the value the finding is about, such as `/slides/4/title`. Empty for the whole document, or for a value in a supplied context such as a loaded catalog."
+        },
+        "scope": {
+          "type": "string",
+          "enum": ["document", "context"],
+          "description": "`document` (the default) when `path` points into the checked presentation, `context` when it points into host-supplied context such as loaded catalog records."
+        },
+        "message": { "type": "string", "minLength": 1, "description": "What is wrong, in a sentence." },
+        "help": { "type": "string", "description": "What to do about it." },
+        "slide": { "type": "integer", "minimum": 0, "description": "Zero-based index of the slide the finding belongs to." },
+        "slideId": { "type": "string", "description": "The id of that slide, when it has one." },
+        "location": { "$ref": "#/$defs/FindingLocation" },
+        "definition": { "type": "string", "description": "A link to the rule's documentation or to the schema constraint or catalog record the finding is about." },
+        "lookup": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Arguments for the `opf schema` or `opf catalog` command that shows the definition, as an argument list rather than a shell string."
+        },
+        "suggestions": { "type": "array", "items": { "$ref": "#/$defs/FindingSuggestion" } },
+        "measured": {
+          "type": "object",
+          "description": "The numbers behind the finding, such as `{ \"ratio\": 2.1, \"needed\": 4.5 }`.",
+          "additionalProperties": { "type": ["number", "string", "boolean", "null"] }
+        },
+        "fixes": { "type": "array", "items": { "$ref": "#/$defs/FindingFix" } },
+        "validation": { "$ref": "#/$defs/ValidationIssue" }
+      }
+    }
+  }
+}

package/dist/spec/schemas/font-scheme.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://openpresentation.org/schema/opf-font-scheme/v1",
   "title": "Font Scheme",
-  "description": "Schema for font-scheme records in the pptx.gallery library. Each scheme pairs a major (heading) and minor (body) font family in the OOXML majorFont/minorFont sense, scoped to a target app (PowerPoint or Google Slides) and a language family (Latin, East Asian, or Complex Script). Font schemes are referenced from OPF documents via design.fontScheme or design.fontScheme.id; the engine resolves the reference against catalogs.fontSchemes (inline) → catalogs.fontSchemes.source → the default catalog at https://www.pptx.gallery/font-schemes. Role overrides on design.fontScheme (heading, body, accent, code) take precedence over the resolved scheme.",
+  "description": "Schema for font-scheme records in the pptx.gallery library. Each scheme pairs a major (heading) and minor (body) font family in the OOXML majorFont/minorFont sense, scoped to a target app (powerpoint or google-slides) and a language family (Latin, East Asian, or Complex Script). Font schemes are referenced from OPF documents via design.fontScheme or design.fontScheme.id; the engine resolves the reference against catalogs.fontSchemes (inline) → catalogs.fontSchemes.source → the default catalog at https://www.pptx.gallery/font-schemes. Role overrides on design.fontScheme (heading, body, accent, code), each a font family name, take precedence over the resolved scheme.",
   "type": "object",
   "required": [
     "$schema",
@@ -80,41 +80,11 @@
       ]
     },
     "code": {
-      "type": "object",
-      "description": "Optional monospaced font for code blocks and inline code. It has the same shape as the OPF FontScheme 'code' role, so a record and an inline design.fontScheme override are interchangeable. OOXML has no code slot, so exporters write this family on code runs. When neither design.fontScheme nor the resolved record defines 'code', engines fall back to Roboto Mono.",
-      "required": [
-        "family"
-      ],
-      "properties": {
-        "family": {
-          "type": "string",
-          "description": "Monospaced font family name.",
-          "examples": [
-            "Consolas",
-            "Courier New"
-          ]
-        },
-        "weight": {
-          "type": "number",
-          "description": "Numeric font weight (e.g., 400 for regular, 700 for bold)."
-        },
-        "style": {
-          "type": "string",
-          "enum": [
-            "normal",
-            "italic"
-          ],
-          "description": "Font style."
-        },
-        "letterSpacing": {
-          "type": "number",
-          "description": "Letter spacing (tracking) in ems."
-        }
-      },
+      "type": "string",
+      "description": "Optional monospaced font family name for code blocks and for inline code runs (TextRun.code). It has the same shape as the OPF FontScheme 'code' role, so a record and an inline design.fontScheme override are interchangeable. OOXML has no code slot, so exporters write this family on code runs. When neither design.fontScheme nor the resolved record defines 'code', engines fall back to Roboto Mono.",
       "examples": [
-        {
-          "family": "Consolas"
-        }
+        "Consolas",
+        "Courier New"
       ]
     },
     "eastAsian": {
@@ -181,32 +151,35 @@
     "app": {
       "type": "string",
       "enum": [
-        "PowerPoint",
-        "Google Slides"
+        "powerpoint",
+        "google-slides"
       ],
-      "description": "Target application this font pairing is intended for."
+      "description": "Target application this font pairing is intended for. Metadata for pickers and catalog filters: no engine changes its output by it."
     },
     "languageFamily": {
       "type": "string",
       "enum": [
         "latin",
         "ea",
-        "cs"
+        "cs",
+        "eastAsian",
+        "complexScript"
       ],
-      "description": "OOXML font-language family this scheme is intended for: 'latin' for Latin-script content, 'ea' for East Asian scripts, 'cs' for Complex Scripts. As the design font scheme, an 'ea' or 'cs' scheme also fills that script slot with its own major/minor families when its languages list is empty or names the presentation language."
+      "description": "Font-language family this scheme is intended for: 'latin' for Latin-script content, 'ea' (or 'eastAsian', the same value) for East Asian scripts, 'cs' (or 'complexScript', the same value) for Complex Scripts. The long names match the 'eastAsian' and 'complexScript' slot keys; the short names match the OOXML a:ea and a:cs elements; core reads both spellings as one value. As the design font scheme, an 'ea'/'eastAsian' or 'cs'/'complexScript' scheme also fills that script slot with its own major/minor families when its languages list is empty or names the presentation language."
     },
     "languages": {
       "type": "array",
       "items": {
-        "type": "string"
+        "type": "string",
+        "pattern": "^[a-z][a-z0-9-]*$"
       },
-      "description": "Optional list of human-readable language names this scheme is curated for. Useful for picker UIs that group fonts by language coverage.",
+      "description": "Optional list of languages catalog ids (see the languages catalog, https://www.pptx.gallery/languages) this scheme is curated for. Useful for picker UIs that group fonts by language coverage. As the design font scheme, an 'ea' or 'cs' scheme fills its script slot only when this list is empty or names the presentation language by id.",
       "examples": [
         [
-          "Chinese (simplified)",
-          "Chinese (traditional)",
-          "Japanese",
-          "Korean"
+          "chinese-simplified",
+          "chinese-traditional",
+          "japanese",
+          "korean"
         ]
       ]
     },

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

@@ -72,157 +72,14 @@
         "Two equal-width columns under a left-aligned slide title. Use when comparing two ideas, before/after pairs, or paired text + image content."
       ]
     },
-    "contentType": {
-      "type": "string",
-      "enum": [
-        "Title",
-        "Text",
-        "List",
-        "Image",
-        "Number",
-        "Metric",
-        "Chart",
-        "Table",
-        "Code",
-        "Video",
-        "Quote",
-        "Timeline"
-      ],
-      "description": "Primary kind of content the layout holds. Drives pickers and AI placement decisions. Metric is the canonical numeric/KPI category; Number remains an accepted legacy label."
-    },
-    "contentMultiple": {
-      "type": "string",
-      "enum": [
-        "None",
-        "1x",
-        "2x",
-        "3x",
-        "4x",
-        "5x",
-        "6x"
-      ],
-      "description": "How many parallel content blocks the layout exposes ('2x' = two-column, '3x' = three-up, etc.)."
-    },
-    "contentAlignment": {
-      "type": "string",
-      "enum": [
-        "None",
-        "Left",
-        "Center"
-      ],
-      "description": "Default horizontal alignment of the content area."
-    },
-    "contentBox": {
-      "type": "boolean",
-      "description": "Whether the content area is rendered inside a visible box / card.",
-      "examples": [
-        false,
-        true
-      ]
-    },
-    "contentTypeChartPrimary": {
-      "type": "string",
-      "enum": [
-        "None",
-        "Top",
-        "Bottom",
-        "Left",
-        "Right"
-      ],
-      "description": "For chart layouts, where the primary chart sits relative to the rest of the content."
-    },
-    "contentTypeImageFill": {
-      "type": "string",
-      "enum": [
-        "None",
-        "Crop",
-        "Fit"
-      ],
-      "description": "For image layouts, how the image fills its slot."
-    },
-    "contentTypeListBullet": {
-      "type": "string",
-      "enum": [
-        "None",
-        "Character",
-        "Image"
-      ],
-      "description": "For list layouts, how bullets are rendered."
-    },
-    "contentTypeListHeading": {
-      "type": "boolean",
-      "description": "For list layouts, whether each list item carries a heading.",
-      "examples": [
-        false,
-        true
-      ]
-    },
-    "slideTag": {
-      "type": "boolean",
-      "description": "Whether the layout includes a small slide-level tag / label region above or near the title.",
-      "examples": [
-        false,
-        true
-      ]
-    },
-    "slideTitle": {
-      "type": "boolean",
-      "description": "Whether the layout includes a slide title region.",
-      "examples": [
-        true,
-        false
-      ]
-    },
-    "slideSubtitle": {
-      "type": "boolean",
-      "description": "Whether the layout includes a slide-level subtitle or supporting-description region. When placeholders is present, this is true exactly when the layout exposes a placeholder with type 'subtitle'.",
-      "examples": [
-        false,
-        true
-      ]
-    },
-    "slideTitleAlignment": {
-      "type": "string",
-      "enum": [
-        "None",
-        "Left",
-        "Center"
-      ],
-      "description": "Horizontal alignment of the slide title region."
-    },
-    "slideImage": {
-      "type": "boolean",
-      "description": "Whether the layout includes a dedicated slide-level image region (separate from any content image).",
-      "examples": [
-        false,
-        true
-      ]
-    },
-    "slideImageAlignment": {
-      "type": "string",
-      "enum": [
-        "None",
-        "Top",
-        "Bottom",
-        "Left",
-        "Right",
-        "Background"
-      ],
-      "description": "Where the slide-level image sits relative to the content."
-    },
-    "slideLayoutDirection": {
-      "type": "string",
-      "enum": [
-        "None",
-        "Horizontal",
-        "Vertical"
-      ],
-      "description": "Axis along which the layout's primary regions are arranged."
+    "design": {
+      "$ref": "#/$defs/DesignHints",
+      "description": "The layout's design hints, with the same keys and values as the deck's design and a slide's design (a slide overrides exactly what its layout sets, by the same name). An absent key means the layout has no opinion. Every key is applied from the record as the lowest-precedence default, per key: the slide's design, then the deck's design, then this record's design, then the engine default, so a layout value nobody overrides is honored without copying it anywhere (a layout's composition.mode still ranks above contentDirection; slideImage.position is the fallback position of a slide image the layout reserves). Composition, the renderer and the PPTX exporter all read the one result."
     },
     "placeholders": {
       "type": "array",
       "items": { "$ref": "#/$defs/Placeholder" },
-      "description": "Ordered regions the layout exposes. The engine fills 'title', 'subtitle', and 'tag' placeholders from Slide.title, Slide.subtitle, and Slide.tag. Other placeholders are content-kind hints for renderers and pickers. Slide content itself lives either in root payload fields or promoted region keys on Slide. Chrome — slide number, footer, date — is not included here; it is owned by Design.header / Design.footer."
+      "description": "Ordered regions the layout exposes. This is the single source of truth for what the layout holds: the content kind, the number of body regions and whether it has a title, subtitle or tag are derived from it (layoutContent in @openpresentation/opf), never stored separately. The engine fills 'title', 'subtitle' and 'tag' placeholders from Slide.title, Slide.subtitle and Slide.tag. The other placeholders are content-kind regions that composition uses to size the body and that pickers use to match layouts. Slide content itself lives either in root payload fields or promoted region keys on Slide. Chrome (slide number, footer, date) is not included here; it is owned by Design.header / Design.footer."
     },
     "tags": {
       "type": "array",
@@ -254,7 +111,7 @@
           "format": "uri",
           "description": "Main preview image (PNG/JPG). Used as the primary visual in picker UIs and previews of the record.",
           "examples": [
-            "https://www.pptx.gallery/layouts/title-left.png"
+            "https://example.com/layouts/title-subtitle.png"
           ]
         },
         "thumbnailSrc": {
@@ -262,7 +119,7 @@
           "format": "uri",
           "description": "Smaller thumbnail preview suited to dense grid views.",
           "examples": [
-            "https://www.pptx.gallery/layouts/title-left.thumbnail.png"
+            "https://example.com/layouts/title-subtitle.thumbnail.png"
           ]
         },
         "vectorSrc": {
@@ -270,7 +127,7 @@
           "format": "uri",
           "description": "SVG / vector preview for crisp scaling at any size.",
           "examples": [
-            "https://www.pptx.gallery/layouts/title-left.svg"
+            "https://www.pptx.gallery/layout-previews/title-subtitle.svg"
           ]
         }
       }
@@ -285,7 +142,7 @@
       "required": [
         "type"
       ],
-      "description": "A single region inside a slide layout. Title, subtitle, and tag placeholders bind to the corresponding Slide fields; other placeholders describe the intended content kind for that region. The array order in the surrounding 'placeholders' field preserves layout region order.",
+      "description": "A single region inside a slide layout. Title, subtitle, and tag placeholders bind to the corresponding Slide fields; every other placeholder describes the content kind that region holds. The array order in the surrounding 'placeholders' field preserves layout region order.",
       "properties": {
         "type": {
           "type": "string",
@@ -294,18 +151,102 @@
             "subtitle",
             "tag",
             "text",
-            "metric",
-            "quote",
-            "timeline",
             "list",
+            "image",
+            "video",
             "chart",
-            "picture",
             "table",
-            "media",
-            "diagram",
-            "code"
+            "code",
+            "metric",
+            "quote",
+            "timeline"
+          ],
+          "description": "The content kind of the region. This is the one OPF content-kind vocabulary: the same words name a slide's payload fields (text, items, image, video, chart, table, code, metric, quote, timeline). 'title', 'subtitle' and 'tag' are the heading kinds and bind to Slide.title, Slide.subtitle and Slide.tag. 'text' holds text and bullets; 'list' holds items. 'image' is filled by an image payload and 'video' by a video payload. 'metric', 'quote', 'timeline', 'chart', 'table' and 'code' are filled by the payload of the same name; a metric region shows the metric payload with its optional label, description, unit, delta, trend and sentiment."
+        }
+      }
+    },
+    "DesignHints": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Design hints a layout carries. The keys and lowercase values are those of the deck's design and a slide's design in opf.schema.json (Design), so a slide overrides a layout by the same name and layout.design can be copied into slide.design unchanged. An absent key means the layout has no opinion. Only the keys the layout sets are stored. scripts/check-spec-integrity.mjs verifies that every key here has the same type and values as its Design counterpart.",
+      "properties": {
+        "titleAlignment": {
+          "type": "string",
+          "enum": [
+            "left",
+            "center",
+            "right"
+          ],
+          "description": "Horizontal alignment of the title placeholder."
+        },
+        "contentAlignment": {
+          "type": "string",
+          "enum": [
+            "left",
+            "center",
+            "right"
+          ],
+          "description": "Horizontal alignment of the body regions."
+        },
+        "contentBox": {
+          "type": "boolean",
+          "description": "Whether the body regions are drawn inside a visible card or surface."
+        },
+        "contentDirection": {
+          "type": "string",
+          "enum": [
+            "horizontal",
+            "vertical"
+          ],
+          "description": "Axis along which parallel body content is arranged: 'vertical' is a column, 'horizontal' a row. Composition applies it when neither the slide nor this layout's composition sets a mode, below the slide's and the deck's design.contentDirection and above automatic selection."
+        },
+        "chartPrimary": {
+          "type": "string",
+          "enum": [
+            "none",
+            "top",
+            "bottom",
+            "left",
+            "right"
+          ],
+          "description": "Where the primary chart sits relative to the other body content. Composition applies it below the slide's and the deck's design.chartPrimary, with the semantics described there."
+        },
+        "imageFill": {
+          "type": "string",
+          "enum": [
+            "crop",
+            "fit"
+          ],
+          "description": "How images fill their region: 'crop' covers the region, 'fit' shows the whole image."
+        },
+        "listBullet": {
+          "type": "string",
+          "enum": [
+            "character",
+            "image"
+          ],
+          "description": "Marker style of lists: 'character' draws the glyph, 'image' draws the deck's icon logo as a picture bullet."
+        },
+        "slideImage": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "position"
           ],
-          "description": "OPF placeholder kind. 'text' and 'list' are flexible textual content regions. 'metric' is a numeric/KPI content region filled by a metric payload, including its optional label, description, unit, delta, and trend. The named kinds describe a specific content role used by pickers, AI generation, and engine defaulting. 'picture' and legacy 'diagram' use image payloads; 'media' uses video. Quote and timeline use their corresponding payload fields."
+          "description": "A slide-level image region the layout reserves, separate from any content image. Its presence is what lets a deck-wide design.slideImage apply to slides on this layout. The image itself comes from the slide or the deck design.",
+          "properties": {
+            "position": {
+              "type": "string",
+              "enum": [
+                "background",
+                "top",
+                "bottom",
+                "left",
+                "right"
+              ],
+              "description": "Where the slide-level image sits relative to the content. 'background' is a full-bleed image behind the content; the other positions give the image a band along that edge. Used when the slide's or deck's design.slideImage gives no position."
+            }
+          }
         }
       }
     },