@openpresentation/opf 0.1.0

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

@@ -0,0 +1,280 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openpresentation.org/schema/opf-layout/v1",
+  "title": "OPF Slide Layout",
+  "description": "Schema for slide-layout records in the pptx.gallery library. Each record describes a semantic slide layout — what regions it exposes and what content kinds those regions are intended to hold. Layouts are referenced from OPF documents via Slide.layout; the engine resolves the reference against catalogs.layouts (inline) → catalogs.layouts.source → the default catalog at https://www.pptx.gallery/layouts. Free-form custom layout names that don't resolve through any catalog fall through to engine-defined layouts.",
+  "type": "object",
+  "required": [
+    "$schema",
+    "id",
+    "name"
+  ],
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "const": "https://openpresentation.org/schema/opf-layout/v1",
+      "description": "Identifies this record as a slide layout in the openpresentation.org catalog."
+    },
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*$",
+      "description": "Stable slug used by OPF documents to reference this layout via Slide.layout. Lowercase kebab-case.",
+      "examples": [
+        "title",
+        "title-subtitle",
+        "chart-1x",
+        "image-bleed"
+      ]
+    },
+    "name": {
+      "type": "string",
+      "description": "Human-readable layout name shown in layout pickers.",
+      "examples": [
+        "Title",
+        "Title Subtitle",
+        "Chart 1x",
+        "Image Bleed"
+      ]
+    },
+    "summary": {
+      "type": "string",
+      "description": "One-sentence positioning of the layout — when to reach for it.",
+      "examples": [
+        "Slide title aligned left over a single content area — flexible workhorse layout.",
+        "Title plus a single chart on the left and supporting copy on the right."
+      ]
+    },
+    "description": {
+      "type": "string",
+      "description": "Longer prose describing the layout structure and ideal use cases.",
+      "examples": [
+        "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",
+        "Chart"
+      ],
+      "description": "Primary kind of content the layout holds. Drives pickers and AI placement decisions."
+    },
+    "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."
+    },
+    "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."
+    },
+    "tags": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Free-form labels for filtering and search.",
+      "examples": [
+        [
+          "title",
+          "minimal"
+        ],
+        [
+          "chart",
+          "kpi"
+        ],
+        [
+          "two-column",
+          "comparison"
+        ]
+      ]
+    },
+    "preview": {
+      "type": "object",
+      "description": "Visual previews of the record, used by picker UIs and inline rendering. All sub-fields are optional; engines fall back gracefully when previews aren't available.",
+      "properties": {
+        "src": {
+          "type": "string",
+          "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"
+          ]
+        },
+        "thumbnailSrc": {
+          "type": "string",
+          "format": "uri",
+          "description": "Smaller thumbnail preview suited to dense grid views.",
+          "examples": [
+            "https://www.pptx.gallery/layouts/title-left.thumbnail.png"
+          ]
+        },
+        "vectorSrc": {
+          "type": "string",
+          "format": "uri",
+          "description": "SVG / vector preview for crisp scaling at any size.",
+          "examples": [
+            "https://www.pptx.gallery/layouts/title-left.svg"
+          ]
+        }
+      }
+    }
+  },
+  "$defs": {
+    "Placeholder": {
+      "type": "object",
+      "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.",
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": [
+            "title",
+            "subtitle",
+            "tag",
+            "text",
+            "list",
+            "chart",
+            "picture",
+            "table",
+            "media",
+            "diagram",
+            "code"
+          ],
+          "description": "OPF placeholder kind. 'text' and 'list' are flexible textual content regions. The named kinds describe a specific content role used by pickers, AI generation, and engine defaulting."
+        }
+      }
+    }
+  }
+}

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

@@ -0,0 +1,207 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openpresentation.org/schema/opf-narrative/v1",
+  "title": "OPF 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').",
+  "type": "object",
+  "required": [
+    "$schema",
+    "id",
+    "name",
+    "beats"
+  ],
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "const": "https://openpresentation.org/schema/opf-narrative/v1"
+    },
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*$",
+      "description": "Stable slug used by OPF documents to reference this template, e.g. 'problem-solution'. Lowercase kebab-case."
+    },
+    "name": {
+      "type": "string",
+      "description": "Human-readable template name, e.g. 'Problem → Solution'."
+    },
+    "summary": {
+      "type": "string",
+      "description": "One-sentence description of when and why to use this narrative."
+    },
+    "description": {
+      "type": "string",
+      "description": "Longer prose describing the narrative arc and ideal use cases. Used by AI-driven generation to seed deck-level direction.",
+      "examples": [
+        "Open with the cost of slow agentic workflows, contrast with what becomes possible at sub-second latency, then walk through our architecture and benchmark results, ending with a concrete adoption ask."
+      ]
+    },
+    "audienceFit": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Audiences this narrative works well for, e.g. ['executives', 'investors', 'customers']."
+    },
+    "durationRange": {
+      "type": "object",
+      "description": "Typical talk-length window this narrative suits.",
+      "properties": {
+        "minMinutes": {
+          "type": "number",
+          "exclusiveMinimum": 0
+        },
+        "maxMinutes": {
+          "type": "number",
+          "exclusiveMinimum": 0
+        }
+      }
+    },
+    "tags": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Free-form labels for filtering and search, e.g. ['business', 'pitch', 'internal']."
+    },
+    "preview": {
+      "type": "object",
+      "description": "Visual previews of the record, used by picker UIs and inline rendering. All sub-fields are optional; engines fall back gracefully when previews aren't available.",
+      "properties": {
+        "src": {
+          "type": "string",
+          "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/narratives/classic-story.png"
+          ]
+        },
+        "thumbnailSrc": {
+          "type": "string",
+          "format": "uri",
+          "description": "Smaller thumbnail preview suited to dense grid views.",
+          "examples": [
+            "https://www.pptx.gallery/narratives/classic-story.thumbnail.png"
+          ]
+        },
+        "vectorSrc": {
+          "type": "string",
+          "format": "uri",
+          "description": "SVG / vector preview for crisp scaling at any size.",
+          "examples": [
+            "https://www.pptx.gallery/narratives/classic-story.svg"
+          ]
+        }
+      }
+    },
+    "beats": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "$ref": "#/$defs/Beat"
+      },
+      "description": "Ordered list of beats that make up the narrative arc."
+    }
+  },
+  "$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.",
+      "required": [
+        "id",
+        "name"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9-]*$",
+          "description": "Stable slug used by Slide.beat to reference this beat. Lowercase kebab-case.",
+          "examples": [
+            "opening",
+            "problem",
+            "evidence",
+            "ask",
+            "next-steps"
+          ]
+        },
+        "name": {
+          "type": "string",
+          "description": "Human-readable beat name, e.g. 'The Problem'.",
+          "examples": [
+            "Opening",
+            "The Problem",
+            "Why Now",
+            "The Ask"
+          ]
+        },
+        "description": {
+          "type": "string",
+          "description": "Curator-written prose that explains what this beat should accomplish.",
+          "examples": [
+            "Quantify the pain customers feel today, with one striking stat the audience can repeat afterward."
+          ]
+        },
+        "instructions": {
+          "type": "string",
+          "description": "Short author-facing instruction for the beat — typically one phrase. Complements 'description' with a concise directive.",
+          "examples": [
+            "Capture audience attention",
+            "Introduce problem",
+            "Detail implementation",
+            "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": "string",
+          "enum": [
+            "text",
+            "list",
+            "image",
+            "shape",
+            "chart",
+            "table",
+            "video",
+            "code",
+            "metric",
+            "quote",
+            "timeline"
+          ],
+          "description": "Default content kind for the beat's slide. Mirrors ContentPayload.type and helps engines choose a sensible layout when only the beat is specified."
+        },
+        "layoutHint": {
+          "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.",
+          "examples": [
+            "section-divider",
+            "title-slide",
+            "title-left",
+            "two-column",
+            "text-left"
+          ]
+        },
+        "thoughtCues": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Optional speaker or thinking cues attached to the beat. Surfaced in presenter notes.",
+          "examples": [
+            [
+              "What pain is the audience feeling right now?",
+              "Why hasn't anyone solved this yet?"
+            ]
+          ]
+        }
+      }
+    }
+  }
+}