@openpresentation/opf 0.12.2 → 0.14.0

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

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://openpresentation.org/schema/opf-narrative/v1",
   "title": "Narrative Template",
-  "description": "Schema for narrative template files in the openpresentation.org catalog. Each template describes a named story arc (e.g. 'problem-solution', 'scqa') as an ordered list of beats. Templates are referenced from OPF documents via narrative — either as a bare id string (e.g. 'classic-story') or as an inline object whose shape matches this schema (sans '$schema').",
+  "description": "Schema for narrative template files in the openpresentation.org catalog. A narrative is a plan: a named story arc (e.g. 'problem-solution', 'scqa') as an ordered list of beats, each saying what its slide must do. A document points at one with the string 'narrative' (a catalog id, an HTTPS URL or a 'pkg:' reference) and links its slides to beats with 'slides[].beat'. A custom narrative is a record in 'catalogs.narratives.records'. Core validate warns about a 'slides[].beat' id the resolved narrative does not define (opf/unknown-beat) and about a root 'duration' outside this record's 'duration' range (opf/duration-outside-narrative), and reports a beat no slide references (opf/unused-beat).",
   "type": "object",
   "required": [
     "$schema",
@@ -63,17 +63,20 @@
       },
       "description": "Audiences this narrative works well for, e.g. ['executive', 'investor', 'customer']."
     },
-    "durationRange": {
+    "duration": {
       "type": "object",
-      "description": "Typical talk-length window this narrative suits.",
+      "additionalProperties": false,
+      "description": "Typical talk length this narrative suits, as a range in minutes. A deck's own target is the root 'duration' (one number); core validate warns when that target lies outside this range, and when 'min' is greater than 'max'.",
       "properties": {
-        "minMinutes": {
+        "min": {
           "type": "number",
-          "exclusiveMinimum": 0
+          "exclusiveMinimum": 0,
+          "description": "Shortest talk length, in minutes, this narrative suits."
         },
-        "maxMinutes": {
+        "max": {
           "type": "number",
-          "exclusiveMinimum": 0
+          "exclusiveMinimum": 0,
+          "description": "Longest talk length, in minutes, this narrative suits."
         }
       }
     },
@@ -126,7 +129,7 @@
   "$defs": {
     "Beat": {
       "type": "object",
-      "description": "A single narrative beat — a labeled segment of the story arc with a specific dramatic purpose. Mirrors the NarrativeBeat definition in opf.schema.json so library entries and inline OPF beats are interchangeable.",
+      "description": "A single narrative beat — a labeled segment of the story arc with a specific dramatic purpose. One beat is one slide: 'type' is that slide's Slide.type and 'layout' is its Slide.layout, so a planner copies them straight into a skeleton deck. Split a heavy beat into several beats rather than giving it several slides.",
       "required": [
         "id",
         "name"
@@ -171,36 +174,25 @@
             "Inspire & conclude"
           ]
         },
-        "slideCount": {
-          "type": "integer",
-          "minimum": 1,
-          "description": "Optional explicit slide count for this beat. Defaults to 1 when omitted; values >1 are reserved for beats that intentionally span multiple slides. Prefer decomposing a heavy beat into multiple beats over setting a high slideCount. The validator emits a warning if the deck's actual count differs significantly.",
-          "examples": [
-            1,
-            2,
-            3
-          ]
-        },
-        "slideType": {
+        "type": {
           "type": "string",
           "enum": [
             "text",
             "list",
             "image",
-            "shape",
+            "video",
             "chart",
             "table",
-            "video",
             "code",
             "metric",
             "quote",
             "timeline"
           ],
-          "description": "Default content kind for the beat's slide. Uses ContentPayload.type names to help engines choose a layout. The legacy shape value is retained for compatibility and requests an image representation; it is not a native ContentPayload type."
+          "description": "Default content kind for the beat's slide: the same values as Slide.type. Helps engines and planners choose a layout when only the beat is known."
         },
-        "layoutHint": {
+        "layout": {
           "type": "string",
-          "description": "Suggested layout id for the beat's opening slide, e.g. 'section-divider', 'title-slide', 'text-left'. Resolves the same way as Slide.layout — against catalogs.layouts and the default catalog at https://www.pptx.gallery/layouts.",
+          "description": "Suggested layout id for the beat's slide, e.g. 'section-divider', 'title-slide', 'text-left'. Resolves the same way as Slide.layout — against catalogs.layouts and the default catalog at https://www.pptx.gallery/layouts.",
           "examples": [
             "section-divider",
             "title-slide",
@@ -214,7 +206,7 @@
           "items": {
             "type": "string"
           },
-          "description": "Optional speaker or thinking cues attached to the beat. Surfaced in presenter notes.",
+          "description": "Optional speaker or thinking cues for the beat: questions the slide should answer. A planner or author turns them into the slide's notes; no engine copies them there on its own.",
           "examples": [
             [
               "What pain is the audience feeling right now?",