Skip to content

layout-schema.md

Latest commit

 

History

History
167 lines (140 loc) · 6.05 KB

layout-schema.md

File metadata and controls

167 lines (140 loc) · 6.05 KB

Layout JSON Schema Reference

Top-Level Structure

{
  "slides": [
    {
      "id": "optional_custom_id",
      "background": { ... },
      "elements": [ ... ]
    }
  ]
}
Field Type Required Description
slides array Yes List of slide specifications

Slide

Field Type Required Default Description
id string No Auto-generated Custom object ID for the slide
background object/null No None Slide background (color or image)
elements array No [] List of elements on the slide

Background

Solid color:

{"color": "#1a1a2e"}

Background image:

{"image_url": "https://example.com/background.jpg"}

Element Types

Text

Field Type Default Description
type string — "text"
id string Auto Custom object ID
content string "" Text content (use \n for line breaks)
runs array — Multi-styled text runs (overrides content)
x float 0.5 X position in inches
y float 0.5 Y position in inches
width float 8 Width in inches
height float 1 Height in inches (auto-expands if text overflows)
font_size float 14 Font size in points
color string — Text color as "#RRGGBB"
font string — Font family name
bold bool false Bold text
italic bool false Italic text
underline bool false Underlined text
strikethrough bool false Strikethrough (ignored for font_size >= 20)
smallCaps bool false Small caps
alignment string — "LEFT", "CENTER", "RIGHT", "JUSTIFIED"
vertical_align string — "TOP", "MIDDLE", "BOTTOM"
background string — Text box background color
line_spacing float — Line spacing (100 = single, 150 = 1.5x)
space_above float — Space above paragraph in points
space_below float — Space below paragraph in points

Text Runs

Multi-styled text within a single text box:

{
  "type": "text",
  "x": 1, "y": 1, "width": 8, "height": 1,
  "runs": [
    {"text": "Bold text ", "bold": true, "font_size": 18},
    {"text": "normal text ", "font_size": 18},
    {"text": "$4.2M", "color": "#27AE60", "bold": true, "font_size": 18}
  ]
}

Each run supports: text, color, font, font_size, bold, italic, underline, strikethrough, smallCaps, alignment.

Table

Field Type Default Description
type string — "table"
id string Auto Custom object ID
headers array [] Header row text values
rows array [] Data rows (array of arrays)
x float 0.5 X position in inches
y float 1.5 Y position in inches
width float 9 Width in inches
height float 3.5 Height in inches
header_bg string "#2C3E50" Header background color
header_color string "#FFFFFF" Header text color
alt_row_bg string "#F5F5F5" Alternating row background
body_color string "#333333" Body text color
font_size float 10 Font size in points
font string — Font family
col_widths array Equal Relative column width ratios

Auto-splitting: If a table has more rows than fit on one slide, it automatically splits across continuation slides. Each continuation slide gets the same headers and a "(continued 2/3)" label.

Shape

Field Type Default Description
type string — "shape"
id string Auto Custom object ID
shape string "RECTANGLE" Shape type (see aliases below)
x float 0 X position in inches
y float 0 Y position in inches
width float 10 Width in inches
height float 0.05 Height in inches
fill string — Fill color as "#RRGGBB"
outline bool/object — false to hide, or {"color": "#hex", "weight": pt, "dash": "DASH"}
content string — Text inside the shape (auto-shrinks to fit)
color string — Text color (when content is set)
font string — Text font (when content is set)
font_size float 14 Text size (when content is set)
bold bool false Bold text (when content is set)
alignment string — Text alignment (when content is set)

Shape aliases:

You write API receives
CIRCLE ELLIPSE
OVAL ELLIPSE
SQUARE RECTANGLE
LINE RECTANGLE
ROUNDED_RECTANGLE ROUND_RECTANGLE
ARROW RIGHT_ARROW
TRIANGLE RIGHT_ARROW_CALLOUT
CALLOUT WEDGE_ROUND_RECTANGLE_CALLOUT

Image

Field Type Default Description
type string — "image"
id string Auto Custom object ID
url string — Image URL (HTTPS required, http:// auto-upgraded)
x float 0.5 X position in inches
y float 0.5 Y position in inches
width float 3 Width in inches
height float 3 Height in inches

Notes:

  • SVG images are silently skipped (unsupported by the Google Slides API)
  • http:// URLs are automatically upgraded to https://
  • Image URLs must be publicly accessible

SlideBuilder.build() Parameters

Parameter Type Description
layout dict The layout JSON (required)
font_overrides dict {"heading": "Font", "body": "Font"} — heading applies to font_size >= 24pt
palette dict {"primary": "#hex", "background": "#hex"} — auto-alternates if >60% same background
known_image_urls set Verified image URLs — unverified unsplash URLs are skipped when this is set