OPF Presentation Schema Reference

This reference documents the author-facing shape of a complete *.opf.json presentation document. It summarizes the canonical schema in spec/schemas/opf.schema.json; the schema remains the source of truth for validators.

Document Contract#

• Schema id: https://openpresentation.org/schema/opf/v1
• Required top-level fields: slides
• Additional top-level fields: not allowed

Top-Level Fields#

Object And Type Reference#

Assets#

• Type: object
• Required fields: none
• Purpose: Reusable asset registry for resources used by slides, charts, metadata, and design. Keys are stable asset ids referenced elsewhere as 'asset:<id>'. Each asset can be a source string or an object with src plus optional metadata.

No named properties.

Asset#

• Type: oneOf:string / object
• Required fields: none
• Purpose: Reusable or inline resource. A string is shorthand for { "src": value }. Source strings accept 'asset:<id>' references, HTTPS URLs, data URIs, relative paths resolved against the OPF file location, or local filesystem paths. Use object form when metadata such as alt text, title or mediaType matters.

No named properties.

Audience#

• Type: anyOf:schema / schema
• Required fields: none
• Purpose: Inline audience metadata for the presentation. Use 'id' to reference an audiences catalog record and override selected fields, or use 'name' for a custom inline audience.
• Conditional requirement: id or name

Purpose#

• Type: anyOf:schema / schema
• Required fields: none
• Purpose: Inline purpose metadata for the presentation. Use 'id' to reference a purposes catalog record and override selected fields, or use 'name' for a custom inline purpose.
• Conditional requirement: id or name

Language#

• Type: anyOf:schema / schema
• Required fields: none
• Purpose: Inline language metadata for the presentation. Use 'id' to reference a languages catalog record and override selected fields, or use 'bcp47' for a custom language tag without a catalog record.
• Conditional requirement: id or bcp47

Tone#

• Type: anyOf:schema / schema
• Required fields: none
• Purpose: Inline tone metadata for the presentation. Use 'id' to reference a tones catalog record and override selected fields, or use 'name' for a custom inline tone.
• Conditional requirement: id or name

Organization#

• Type: object
• Required fields: id, name
• Purpose: An organization associated with the presentation, typically the presenting company, but also hosts, partners, clients, or sponsors. The primary organization (role 'primary', else the first one) supplies the default deck logo (unless design.logo overrides it), the 'organization' header/footer field (its name) and the 'socials' field (its socials). Every field is also a built-in variable ('{{organization.name}}', 'var:organization.logo', 'organization.<id>.<field>'). Nothing else about an organ...

Speaker#

• Type: object
• Required fields: id, name
• Purpose: A person presenting the deck. A speaker is drawn only through built-in variables ('{{speaker.name}}' inside any string, 'var:speaker.photo' as a whole image field) and the 'speaker' header/footer field (the first speaker's name and title). No layout, cover or bio slide places a speaker on its own. See docs/templates-and-variables.md.

Socials#

• Type: object
• Required fields: none
• Purpose: Social media handles or URLs, keyed by platform id from the 'socialPlatforms' catalog. Each value is a string either a full URL or a platform handle (e.g., '@acme'). The catalog record for each platform carries the URL pattern and handle prefix that engines use to render and link the profile URL, plus brand color and themed icons as catalog metadata for authoring UIs (engines render the profile URL, not icons or brand colors). Keys resolve to the 'id' of a 'socialPlatforms' catalog record. Re...

No named properties.

Design#

• Type: object
• Required fields: none
• Purpose: Visual design system applied to the presentation; individual slides may override fields via Slide.design.

Theme#

• Type: object
• Required fields: none
• Purpose: Theme bundle used by the design system. In design.theme, 'id' resolves a themes catalog record as the base; any sibling fields override the resolved theme. The string shorthand on design.theme is equivalent to setting only 'id'.

ColorScheme#

• Type: object
• Required fields: none
• Purpose: Color palette used by the design system. Every slot and role is a hex color ('#RGB', '#RRGGBB' or '#RRGGBBAA'); a color-scheme name or a 'var:<id>' reference is not valid here, because those resolve through the scheme. The slot fields (accent1-accent6, dark1, dark2, light1, light2, hyperlink, followedHyperlink) mirror color-scheme.schema.json (https://openpresentation.org/schema/opf-color-scheme/v1) so library records and inline OPF overrides are interchangeable on those fields. Two parallel...

FontScheme#

• Type: object
• Required fields: none
• Purpose: Typography selections used by the design system. The pair fields (major, minor) and refinement fields (type, app, languageFamily) mirror font-scheme.schema.json (https://openpresentation.org/schema/opf-font-scheme/v1) so library records and inline OPF overrides are interchangeable on those fields. Two parallel models are supported and may be mixed: - OOXML pairs (major, minor) - heading and body family names that round-trip directly to PowerPoint majorFont/minorFont entries. - Abstract roles...

SlideDesign#

• Type: allOf:ref:Design + schema
• Required fields: none
• Purpose: A slide's design: every Design field except dimensions. A PPTX has one slide size, so the size is set once, on the deck's design.dimensions (or its theme), and a slide's design cannot set it. A slide-level theme whose resolved dimensions differ from the deck's is a validate warning (opf/slide-theme-dimensions); exporting such a deck to PPTX fails with mixed-slide-dimensions.

No named properties.

DimensionPreset#

• Type: enum:16:9 | 4:3 | 16:10 | 1:1 | 4:5 | 9:16 | letter | a4 | widescreen | standard
• Required fields: none
• Purpose: Named dimension preset; chooses both aspect ratio and physical size. 'widescreen' is an alias for 16:9 in PowerPoint widescreen size; 'standard' is an alias for 4:3 in PowerPoint standard size. The social-feed ratios keep the widescreen short edge of 7.5 in: 1:1 is 7.5 x 7.5 in, 4:5 is 7.5 x 9.375 in and 9:16 is 7.5 x 13.333 in (portrait).

No named properties.

Dimensions#

• Type: object
• Required fields: none
• Purpose: Slide dimensions; either pick a preset or specify custom inches.

ThemeBackgroundSlot#

• Type: enum:light1 | light2 | dark1 | dark2
• Required fields: none
• Purpose: PowerPoint theme-controlled slide background slot from the active color scheme. These are slots, not assumptions about actual colors: light1 is usually white and dark1 is usually black by convention, but the color scheme controls the real values.

No named properties.

HexColor#

• Type: string
• Required fields: none
• Purpose: Hex color shorthand accepted by selected string fields.

No named properties.

ColorRef#

• Type: anyOf:ref:HexColor / enum:accent1 | accent2 | accent3 | accent4 | accent5 | accent6 | dark1 | dark2 | light1 | light2 | hyperlink | followedHyperlink | primary | secondary | accent | background | surface | surfaceAlt | text | textSecondary / string
• Required fields: none
• Purpose: A color value or reference, enforced on styled table cell fill and text colors, cell border colors, solid background colors, gradient stop colors and pattern foreground and background colors. Three forms: - Literal hex: '#RGB', '#RRGGBB', or '#RRGGBBAA'. - Color-scheme name, resolved through the effective color scheme after design resolution: an OOXML slot ('accent1'-'accent6', 'dark1', 'dark2', 'light1', 'light2', 'hyperlink', 'followedHyperlink') or an abstract role ('primary', 'secondary',...

No named properties.

Variables#

• Type: object
• Required fields: none
• Purpose: 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: ex...

No named properties.

Variable#

• Type: oneOf:ref:HexColor / ref:ColorVariable / ref:TextVariable / ref:NumberVariable / ref:DateVariable / ref:ImageVariable / ref:UrlVariable / ref:ListVariable
• Required fields: none
• Purpose: 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.

No named properties.

ColorVariable#

• Type: object
• Required fields: type
• Purpose: 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 fields: type
• Purpose: 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 fields: type
• Purpose: A number. '{{<id>}}' inserts it as text using 'format'; 'var:<id>' as a whole field supplies the number itself (chart values, font sizes).

NumberFormat#

• Type: string
• Required fields: none
• Purpose: Number display pattern, shared by NumberVariable.format, data column formats (DataColumn.format) and table cell formats (StyledTableCell.format). An optional literal prefix, a numeric part of '#', '0', ',' and '.', and an optional literal suffix. '0' pads digits, '#' is optional, ',' groups thousands, digits after '.' fix the decimals ('0' required, '#' optional), and a '%' in the prefix or suffix multiplies the value by 100. English separators only. A format applies only to number values; st...

No named properties.

DateVariable#

• Type: object
• Required fields: type
• Purpose: 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 fields: type
• Purpose: 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 fields: type
• Purpose: 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 fields: type
• Purpose: 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#

• Type: oneOf:ref:ThemeBackgroundSlot / ref:HexColor
• Required fields: none
• Purpose: String shorthand for a background. Theme slots ('light1', 'light2', 'dark1', 'dark2') are equivalent to { type: 'theme', slot: value }; hex colors are equivalent to { type: 'solid', color: value }.

No named properties.

Background#

• Type: oneOf:ref:ThemeBackground / ref:SolidBackground / ref:GradientBackground / ref:ImageBackground / ref:PatternBackground
• Required fields: none
• Purpose: Background fill applied to slides. Theme backgrounds preserve PowerPoint's color-scheme background choice; other variants represent fixed background fills.

No named properties.

ThemeBackground#

• Type: object
• Required fields: type, slot
• Purpose: Theme-controlled PowerPoint slide background. The slot is resolved through the active color scheme and remains theme-aware.

SolidBackground#

• Type: object
• Required fields: type, color
• Purpose: Fixed solid slide background fill.

GradientBackground#

• Type: object
• Required fields: type, gradient
• Purpose: Fixed gradient slide background fill.

ImageBackground#

• Type: object
• Required fields: type, image
• Purpose: Fixed image slide background fill.

PatternBackground#

• Type: object
• Required fields: type, pattern
• Purpose: Fixed pattern slide background fill.

LogoSet#

• Type: object
• Required fields: none
• Purpose: 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, wordmar...

Watermark#

• Type: oneOf:schema / schema
• Required fields: opacity
• Purpose: Decorative watermark: an image ('src') or a text stamp ('text'), exactly one of the two, with its opacity. An image is drawn once per slide, contained and centered in a fixed frame (the middle 40% of the slide width and height, from 30% to 70% on each axis). A text watermark is one line of text in the heading font and the theme text color at the given opacity, centered on the slide and rotated 30 degrees counterclockwise (rising to the right), sized to span at most 70% of the slide width and...

HeaderFooter#

• Type: object
• Required fields: none
• Purpose: Repeated header or footer content split into left, center, and right zones. Header/footer content is slide furniture, separate from the main slide content payloads.

HeaderFooterItem#

• Type: object
• Required fields: none
• Purpose: One header/footer zone. Every configured field renders; fields in one zone stack top to bottom in the order logo, image, text, organization, speaker, socials, section, slide number, date. Put a date and a slide number in different zones to keep each on the zone's single line.

Slide#

• Type: object
• Required fields: none
• Purpose: A single slide. Content can be authored as a full-slide root payload, or inside promoted named region keys such as 'left', 'center+right', and 'top:left'.

ContentPayload#

• Type: allOf:schema + schema + schema + schema + schema + schema + schema + schema + schema + schema + schema + schema
• Required fields: none
• Purpose: A content leaf or recursively composed group. A group contains blocks and optional composition; it cannot mix blocks with leaf payload fields. Groups may nest up to 32 levels.

Quote#

• Type: object
• Required fields: text
• Purpose: Quote content with optional attribution metadata. Use 'text' for the quoted text, 'attribution' for the credited person or organization, 'role' for that person's title and organization, 'photo' for their headshot and 'source' for a citation or URL. A string value in a quote field is shorthand for { "text": value }.

Code#

• Type: object
• Required fields: source
• Purpose: Code content with optional rendering metadata. Use 'source' for the code text, 'language' for syntax highlighting, 'filename' when the rendered block should show a file label, and 'highlight' to emphasize lines. A string value in a code field is shorthand for { "source": value }.

Metric#

• Type: object
• Required fields: value
• Purpose: Metric content with optional display metadata. Use 'value' for the primary value, 'label' for the metric name, 'description' for supporting context, 'unit' for a suffix/currency marker, 'delta' for change, 'trend' for direction, and 'sentiment' for whether the change is good news. A string or number value in a metric field is shorthand for { "value": value }; numeric values remain numbers and are formatted by renderers.

Timeline#

• Type: oneOf:array<ref:TimelineEvent> / object
• Required fields: none
• Purpose: Timeline content. An array is shorthand for { "events": value }; object form carries optional name and description metadata.

No named properties.

TimelineEvent#

• Type: object
• Required fields: what
• Purpose: A single event inside a timeline content payload.

ListItem#

• Type: oneOf:string / array<ref:TextRun> / object
• Required fields: none
• Purpose: A flat item inside a list. Strings cover the common case, TextRun[] supports inline rich text without an object wrapper, and object form adds description and nesting depth without creating nested slide content payloads.

No named properties.

BulletItem#

• Type: oneOf:string / array<ref:TextRun> / object
• Required fields: none
• Purpose: A flat bullet item. Strings cover the common case, TextRun[] supports inline rich text without an object wrapper, and object form adds nesting depth without list-item descriptions.

No named properties.

NumberingStyle#

• Type: enum:arabic | roman-upper | roman-lower | alpha-upper | alpha-lower
• Required fields: none
• Purpose: 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.

No named properties.

Numbering#

• Type: object
• Required fields: none
• Purpose: Numbering of one list level.

NumberingSpec#

• Type: oneOf:ref:NumberingStyle / ref:Numbering / array<oneOf:ref:NumberingStyle / ref:Numbering>
• Required fields: none
• Purpose: 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).

No named properties.

TextRun#

• Type: oneOf:string / object
• Required fields: none
• Purpose: A contiguous run of text. Strings cover unformatted spans; object form adds character formatting.

No named properties.

Caption#

• Type: oneOf:string / array<ref:TextRun> / object
• Required fields: none
• Purpose: 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.

No named properties.

Reference#

• Type: object
• Required fields: id, text
• Purpose: 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.

Chart#

• Type: object
• Required fields: type, data
• Purpose: Chart content. The chart object keeps chart-specific fields together so slides and regions do not expose loose chart fields.

ChartAxisTitles#

• Type: object
• Required fields: none
• Purpose: Titles for the 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; 'secondary' is the secondary value axis of a combo chart.

ChartHighlight#

• Type: object
• Required fields: none
• Purpose: Which series and categories a chart emphasizes. Names are matched exactly: series by data column name (after any 'fields' selection; a series is a plotted value column), categories by row label (the first column, or mapping.category), as text. A category label shared by several rows highlights each of them.

ChartDataLabels#

• Type: object
• Required fields: none
• Purpose: Data label settings. A label shows the selected content parts in the fixed order category, value, percent, joined by the separator.

Table#

• Type: object
• Required fields: none
• Purpose: Table content, inline or dataset-backed. An inline table has 'rows' (required) and optional 'columns'. A dataset-backed table has 'dataset' (required) and optional 'fields', and no 'rows' or 'columns': it takes its headers, rows and column formats from the dataset (per-cell styles need an inline table).
• Conditional requirement: dataset, or otherwise rows

ChartData#

• Type: object
• Required fields: columns, rows
• Purpose: Inline tabular data driving a chart. The first column usually supplies category/x-axis labels; subsequent columns are plotted measures unless 'chart.mapping' or a chart type maps them differently. Value cells are numbers; a string is read only in strict decimal syntax ('12', '-3.5', '1e6'), and anything else ('12%', '$5', '(5)', '1,234') is a gap and a 'chart-value-not-numeric' warning.

DataColumn#

• Type: object
• Required fields: name
• Purpose: A named data column with an optional number format. Anywhere a chart or dataset column is a string it may be a DataColumn; the string form is { "name": value } with no format. A table column header may also be a DataColumn.

DataSourceRef#

• Type: object
• Required fields: src
• Purpose: Provenance of inline data or a dataset: the file, sheet and range it came from and when. Engines never read, fetch or refresh it; they keep it through editing, export and re-import. Re-import the data to update it.

DatasetId#

• Type: string
• Required fields: none
• Purpose: Id of an entry in the top-level datasets map (the assets id pattern).

No named properties.

DatasetFields#

• Type: array<string>
• Required fields: none
• Purpose: Dataset column names to use, in order, each at most once. Selects and orders the dataset's columns; an unknown name is a 'dataset-field-unknown' error.

No named properties.

Datasets#

• Type: object
• Required fields: none
• Purpose: Shared data tables keyed by id (the assets id pattern). Charts reference one with 'chart.data': { "dataset": "<id>" } and tables with 'table': { "dataset": "<id>" }.

No named properties.

Dataset#

• Type: object
• Required fields: columns, rows
• Purpose: One shared data table: named columns (strings or DataColumn objects with a number format) and rows of scalar cells. Column names are unique ('data-column-duplicate' error). Rich text and styling belong in an inline table.

DatasetRef#

• Type: object
• Required fields: dataset
• Purpose: Chart data taken from a top-level dataset. Engines inline it before plotting; 'chart.mapping' names columns after the 'fields' selection.

ChartMapping#

• Type: object
• Required fields: none
• Purpose: Series mapping by column name (after any 'fields' selection). Mapping only selects and orders columns; pie, doughnut and other single-series constructs still plot one series. An unknown name is a 'chart-mapping-unknown-column' error; a series that repeats the category or X column, and an X column on a chart type without an X axis, are dropped with a 'chart-mapping-adapted' warning.

ChartDataCell#

• Type: oneOf:string / number / boolean / null
• Required fields: none
• Purpose: A cell in inline chart data.

No named properties.

TableCell#

• Type: oneOf:ref:TableCellValue / ref:StyledTableCell
• Required fields: none
• Purpose: A scalar, rich-run array, or styled/spanning cell object. Existing scalar and rich forms remain valid.

No named properties.

TableCellValue#

• Type: oneOf:string / number / boolean / null / array<ref:TextRun>
• Required fields: none
• Purpose: A scalar table value or canonical rich text runs, without cell decoration or geometry.

No named properties.

StyledTableCell#

• Type: object
• Required fields: value
• Purpose: A cell with explicit visual style or merged geometry. Its position remains its array column index; use null placeholders for every covered grid position.

TableCellStyle#

• Type: object
• Required fields: none
• Purpose: Cell appearance. Sizes use reference pixels at a 720-pixel canvas short edge and scale with the slide.

TableCellPadding#

• Type: object
• Required fields: none
• Purpose: Text insets in reference pixels. Defaults: top 8, right 10, bottom 4, left 10.

TableCellBorder#

• Type: object
• Required fields: color, width
• Purpose: One explicit cell border.

Catalogs#

• Type: object
• Required fields: none
• Purpose: Catalog overrides for the in-document references. Every property is optional. The default catalog for a kind lives at https://www.pptx.gallery/<kind> (e.g. https://www.pptx.gallery/narratives, https://www.pptx.gallery/themes). pptx.gallery is its canonical publisher: GET https://www.pptx.gallery/<kind>/index.json (or https://www.pptx.gallery/<kind> with Accept: application/json) returns a catalog index (https://openpresentation.org/schema/opf-catalog-index/v1) and https://www.pptx.gallery/<ki...

CatalogEntry#

• Type: object
• Required fields: none
• Purpose: A catalog override for one record kind. 'source' replaces the default registry; 'records' adds inline records that take precedence over anything fetched from a source. Either or both may be provided; both omitted means the kind uses its default catalog.

CatalogSource#

• Type: string
• Required fields: none
• Purpose: Catalog source location. Accepts: - A bare URL pointing at a catalog directory (e.g. 'https://acme.com/decks/narratives'); record ids resolve to '<base>/<id>.json'. - A URL pointing at an index file (e.g. 'https://acme.com/decks/narratives/index.json'); records are resolved relative to the index file's directory and the index entries describe what's available. Index files follow https://openpresentation.org/schema/opf-catalog-index/v1; the default catalog's index is https://www.pptx.gallery/<...

No named properties.

Composition#

• Type: object
• Required fields: none
• Purpose: Portable dynamic composition. Slide fields override the resolved layout. Nested groups arrange their children independently, inheriting only minFontSize and overflow. Explicit promoted regions retain their positions.