331 lines
13 KiB
Markdown
331 lines
13 KiB
Markdown
# PaperJSX JSON Layout Spec — Schema Reference
|
||
|
||
This document contains the complete input schemas for all PaperJSX document generation tools. Use these schemas to produce valid JSON input.
|
||
|
||
---
|
||
|
||
## PPTX Presentation
|
||
|
||
**Tool:** `generate_presentation`
|
||
**Package:** `@paperjsx/json-to-pptx`
|
||
|
||
### Top-level fields
|
||
|
||
| Field | Type | Required | Default | Description |
|
||
|-------|------|----------|---------|-------------|
|
||
| `title` | string | yes | — | Presentation title |
|
||
| `author` | string | no | — | Author/presenter name |
|
||
| `company` | string | no | — | Company name |
|
||
| `date` | string | no | — | Presentation date |
|
||
| `slides` | SlideContent[] | yes | — | Array of slides (1–50) |
|
||
| `theme` | enum | no | `"corporate"` | `"corporate"`, `"modern"`, `"minimal"`, `"dark"`, `"gradient"` |
|
||
| `primary_color` | string | no | — | Primary brand color (hex) |
|
||
| `secondary_color` | string | no | — | Secondary accent color (hex) |
|
||
| `logo_url` | string (URL) | no | — | Company logo URL |
|
||
| `format` | enum | no | `"pptx"` | `"pptx"` or `"pdf"` |
|
||
| `aspect_ratio` | enum | no | `"16:9"` | `"16:9"` or `"4:3"` |
|
||
| `include_slide_numbers` | boolean | no | `true` | Show slide numbers |
|
||
| `include_footer` | boolean | no | `true` | Show footer |
|
||
|
||
### Slide types
|
||
|
||
Each slide has a `type` field that determines its structure.
|
||
|
||
#### `"title"` — Title slide
|
||
|
||
| Field | Type | Required | Description |
|
||
|-------|------|----------|-------------|
|
||
| `type` | `"title"` | yes | — |
|
||
| `title` | string | yes | Main title text |
|
||
| `subtitle` | string | no | Subtitle text |
|
||
| `background_image_url` | string (URL) | no | Background image |
|
||
|
||
#### `"content"` — Bullet content slide
|
||
|
||
| Field | Type | Required | Default | Description |
|
||
|-------|------|----------|---------|-------------|
|
||
| `type` | `"content"` | yes | — | — |
|
||
| `heading` | string | yes | — | Slide heading |
|
||
| `bullets` | string[] | yes | — | Bullet points |
|
||
| `image_url` | string (URL) | no | — | Optional image |
|
||
| `image_position` | enum | no | `"right"` | `"left"` or `"right"` |
|
||
|
||
#### `"chart"` — Chart slide
|
||
|
||
| Field | Type | Required | Description |
|
||
|-------|------|----------|-------------|
|
||
| `type` | `"chart"` | yes | — |
|
||
| `heading` | string | yes | Slide heading |
|
||
| `chart` | ChartConfig | yes | Chart configuration (see below) |
|
||
| `caption` | string | no | Chart caption or source |
|
||
|
||
**ChartConfig:**
|
||
|
||
| Field | Type | Required | Description |
|
||
|-------|------|----------|-------------|
|
||
| `type` | enum | yes | `"line"`, `"bar"`, `"pie"`, `"area"` |
|
||
| `data` | object[] | yes | Array of data points (key-value records) |
|
||
| `x_key` | string | yes | Key for X-axis |
|
||
| `y_keys` | string[] | yes | Keys for Y-axis series |
|
||
| `colors` | string[] | no | Hex colors for each series |
|
||
|
||
#### `"two_column"` — Two-column layout
|
||
|
||
| Field | Type | Required | Description |
|
||
|-------|------|----------|-------------|
|
||
| `type` | `"two_column"` | yes | — |
|
||
| `heading` | string | yes | Slide heading |
|
||
| `left` | string[] | yes | Left column bullet points |
|
||
| `right` | string[] | yes | Right column bullet points |
|
||
| `left_heading` | string | no | Left column sub-heading |
|
||
| `right_heading` | string | no | Right column sub-heading |
|
||
|
||
#### `"quote"` — Quote slide
|
||
|
||
| Field | Type | Required | Description |
|
||
|-------|------|----------|-------------|
|
||
| `type` | `"quote"` | yes | — |
|
||
| `quote` | string | yes | Quote text |
|
||
| `attribution` | string | no | Quote source |
|
||
| `background_color` | string | no | Background color (hex) |
|
||
|
||
#### `"image"` — Image slide
|
||
|
||
| Field | Type | Required | Default | Description |
|
||
|-------|------|----------|---------|-------------|
|
||
| `type` | `"image"` | yes | — | — |
|
||
| `heading` | string | no | — | Optional heading |
|
||
| `image_url` | string (URL) | yes | — | Main image URL |
|
||
| `caption` | string | no | — | Image caption |
|
||
| `fit` | enum | no | `"contain"` | `"contain"`, `"cover"`, `"fill"` |
|
||
|
||
#### `"comparison"` — Comparison slide
|
||
|
||
| Field | Type | Required | Description |
|
||
|-------|------|----------|-------------|
|
||
| `type` | `"comparison"` | yes | — |
|
||
| `heading` | string | yes | Slide heading |
|
||
| `items` | ComparisonItem[] | yes | 2–4 comparison items |
|
||
|
||
**ComparisonItem:** `{ label: string, value: string, highlight?: boolean }`
|
||
|
||
#### `"stats"` — Stats/metrics slide
|
||
|
||
| Field | Type | Required | Description |
|
||
|-------|------|----------|-------------|
|
||
| `type` | `"stats"` | yes | — |
|
||
| `heading` | string | yes | Slide heading |
|
||
| `stats` | StatItem[] | yes | 1–4 stat items |
|
||
|
||
**StatItem:** `{ label: string, value: string, change?: string, trend?: "up" | "down" | "neutral" }`
|
||
|
||
---
|
||
|
||
## PDF Invoice
|
||
|
||
**Tool:** `generate_invoice`
|
||
**Package:** `@paperjsx/json-to-pdf`
|
||
|
||
| Field | Type | Required | Default | Description |
|
||
|-------|------|----------|---------|-------------|
|
||
| `invoice_number` | string | yes | — | Unique invoice ID |
|
||
| `issue_date` | string | yes | — | ISO 8601 (YYYY-MM-DD) |
|
||
| `due_date` | string | yes | — | ISO 8601 (YYYY-MM-DD) |
|
||
| `from` | InvoiceSender | yes | — | Sender info (see below) |
|
||
| `to` | Address | yes | — | Recipient info |
|
||
| `items` | LineItem[] | yes | — | Line items (min: 1) |
|
||
| `currency` | enum | no | `"USD"` | ISO 4217 code: USD, EUR, GBP, INR, BRL, AUD, CAD, JPY, CNY, CHF, SGD, HKD |
|
||
| `tax_rate` | number | no | `0` | Default tax rate (0–100) |
|
||
| `discount_total` | number | no | — | Discount amount |
|
||
| `shipping` | number | no | — | Shipping cost |
|
||
| `notes` | string | no | — | Additional notes/terms |
|
||
| `payment_instructions` | string | no | — | Payment instructions |
|
||
| `purchase_order` | string | no | — | PO number |
|
||
| `theme` | enum | no | — | `"corporate"`, `"modern"`, `"minimal"`, `"academic"`, `"legal"` |
|
||
|
||
**InvoiceSender** extends Address with: `logo_url?: string (URL)`
|
||
|
||
**Address:** `{ name, address_line_1, address_line_2?, city, state?, postal_code, country, email?, phone?, tax_id? }`
|
||
|
||
**LineItem:** `{ description: string, quantity: number, unit_price: number, tax_rate?: number (0–100), discount?: number (0–100) }`
|
||
|
||
---
|
||
|
||
## PDF Report
|
||
|
||
**Tool:** `generate_report`
|
||
**Package:** `@paperjsx/json-to-pdf`
|
||
|
||
| Field | Type | Required | Default | Description |
|
||
|-------|------|----------|---------|-------------|
|
||
| `title` | string | yes | — | Report title |
|
||
| `subtitle` | string | no | — | Subtitle |
|
||
| `author` | string | no | — | Author name |
|
||
| `date` | string | no | — | ISO 8601 (YYYY-MM-DD) |
|
||
| `version` | string | no | — | e.g. "v1.0", "Draft" |
|
||
| `content` | string | yes | — | Full markdown content |
|
||
| `include_toc` | boolean | no | `true` | Auto-generate table of contents |
|
||
| `include_cover` | boolean | no | `true` | Generate cover page |
|
||
| `page_numbers` | boolean | no | `true` | Show page numbers |
|
||
| `toc_depth` | number | no | `3` | Max heading level in TOC (1–6) |
|
||
| `theme` | enum | no | — | `"corporate"`, `"modern"`, `"minimal"`, `"academic"`, `"legal"` |
|
||
| `primary_color` | string | no | — | Hex color for headings |
|
||
| `font_family` | enum | no | `"sans"` | `"sans"`, `"serif"`, `"mono"` |
|
||
| `page_format` | enum | no | `"a4"` | `"a4"`, `"letter"`, `"legal"` |
|
||
| `orientation` | enum | no | `"portrait"` | `"portrait"`, `"landscape"` |
|
||
| `header_logo_url` | string (URL) | no | — | Logo for header |
|
||
| `footer_text` | string | no | — | Footer text |
|
||
|
||
**Markdown content supports:** headings (#–######), GFM tables, fenced code blocks, images via URL, bullet/numbered lists, blockquotes, bold/italic/strikethrough, horizontal rules, links.
|
||
|
||
---
|
||
|
||
## PDF Chart Document
|
||
|
||
**Tool:** `generate_chart_document`
|
||
**Package:** `@paperjsx/json-to-pdf`
|
||
|
||
| Field | Type | Required | Default | Description |
|
||
|-------|------|----------|---------|-------------|
|
||
| `title` | string | yes | — | Document title |
|
||
| `subtitle` | string | no | — | Subtitle |
|
||
| `author` | string | no | — | Author name |
|
||
| `date` | string | no | — | ISO 8601 |
|
||
| `charts` | ChartConfig[] | yes | — | 1–4 chart configurations |
|
||
| `analysis_text` | string | no | — | Markdown analysis/commentary |
|
||
| `key_insights` | string[] | no | — | Bullet points of insights |
|
||
| `include_data_table` | boolean | no | `false` | Include raw data as table |
|
||
| `theme` | enum | no | — | `"corporate"`, `"modern"`, `"minimal"`, `"academic"`, `"legal"` |
|
||
| `page_format` | enum | no | `"a4"` | `"a4"`, `"letter"`, `"legal"` |
|
||
| `primary_color` | string | no | — | Hex color for accents |
|
||
|
||
**ChartConfig:**
|
||
|
||
| Field | Type | Required | Default | Description |
|
||
|-------|------|----------|---------|-------------|
|
||
| `type` | enum | yes | — | `"line"`, `"bar"`, `"pie"`, `"area"`, `"scatter"`, `"composed"` |
|
||
| `title` | string | no | — | Chart title |
|
||
| `data` | object[] | yes | — | Array of data points (key-value records) |
|
||
| `x_key` | string | yes | — | Key for X-axis |
|
||
| `y_keys` | string[] | yes | — | Keys for Y-axis series |
|
||
| `colors` | string[] | no | — | Hex colors for each series |
|
||
| `show_legend` | boolean | no | `true` | Show legend |
|
||
| `show_grid` | boolean | no | `true` | Show grid lines |
|
||
| `y_axis_label` | string | no | — | Y-axis label |
|
||
| `x_axis_label` | string | no | — | X-axis label |
|
||
| `stacked` | boolean | no | — | Stack bars/areas |
|
||
|
||
---
|
||
|
||
## XLSX Spreadsheet
|
||
|
||
**Tool:** `generate_spreadsheet`
|
||
**Package:** `@paperjsx/json-to-xlsx`
|
||
|
||
| Field | Type | Required | Default | Description |
|
||
|-------|------|----------|---------|-------------|
|
||
| `document` | SpreadsheetDoc | yes | — | Spreadsheet document JSON |
|
||
| `output_filename` | string | no | — | Safe .xlsx filename (alphanumeric, dots, hyphens, underscores) |
|
||
| `render_options` | object | no | — | `{ deterministic?, large_dataset?, row_chunk_size? (max 100K), string_strategy?: "auto"|"sharedStrings"|"inlineStrings" }` |
|
||
| `validate_after_render` | boolean | no | `true` | Validate output after generation |
|
||
| `attempt_repair_if_needed` | boolean | no | `true` | Auto-repair if validation finds issues |
|
||
|
||
**SpreadsheetDoc:**
|
||
|
||
```json
|
||
{
|
||
"meta": {
|
||
"title": "string",
|
||
"creator": "string"
|
||
},
|
||
"sheets": [
|
||
{
|
||
"name": "Sheet1",
|
||
"rows": [
|
||
{
|
||
"cells": [
|
||
{ "value": "string or number or boolean" }
|
||
]
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## DOCX Report
|
||
|
||
**Tool:** `generate_report_docx`
|
||
**Package:** `@paperjsx/json-to-docx`
|
||
|
||
| Field | Type | Required | Default | Description |
|
||
|-------|------|----------|---------|-------------|
|
||
| `title` | string | yes | — | Report title |
|
||
| `subtitle` | string | no | — | Subtitle |
|
||
| `author` | string | no | — | Author name |
|
||
| `date` | string | no | — | YYYY-MM-DD format |
|
||
| `sections` | Section[] | yes | — | Report sections (min: 1) |
|
||
| `include_toc` | boolean | no | `true` | Table of contents |
|
||
| `theme` | enum | no | `"corporate"` | `"corporate"`, `"modern"`, `"classic"`, `"academic"`, `"minimal"` |
|
||
| `page_size` | enum | no | `"a4"` | `"a4"`, `"letter"`, `"legal"` |
|
||
| `orientation` | enum | no | `"portrait"` | `"portrait"`, `"landscape"` |
|
||
| `header_text` | string | no | — | Header text |
|
||
| `footer_text` | string | no | — | Footer text |
|
||
| `include_page_numbers` | boolean | no | `true` | Show page numbers |
|
||
|
||
**Section:** `{ heading: string, level?: number (1–4, default 1), content: string, bullets?: string[] }`
|
||
|
||
Content paragraphs are separated by double newlines.
|
||
|
||
---
|
||
|
||
## DOCX Contract
|
||
|
||
**Tool:** `generate_contract_docx`
|
||
**Package:** `@paperjsx/json-to-docx`
|
||
|
||
| Field | Type | Required | Default | Description |
|
||
|-------|------|----------|---------|-------------|
|
||
| `title` | string | yes | — | Contract title |
|
||
| `effective_date` | string | yes | — | Effective date |
|
||
| `parties` | Party[] | yes | — | Contracting parties (min: 2) |
|
||
| `recitals` | string[] | no | — | WHEREAS clauses/preamble |
|
||
| `clauses` | Clause[] | yes | — | Contract clauses (min: 1) |
|
||
| `signatures` | Signature[] | no | — | Signature blocks |
|
||
| `theme` | enum | no | `"classic"` | `"corporate"`, `"classic"`, `"academic"` |
|
||
| `page_size` | enum | no | `"letter"` | `"a4"`, `"letter"`, `"legal"` |
|
||
|
||
**Party:** `{ name: string, address: string, role: string }`
|
||
|
||
**Clause:** `{ number: string, title: string, content: string, subclauses?: [{ label: string, content: string }] }`
|
||
|
||
**Signature:** `{ name: string, title: string, party: string }`
|
||
|
||
---
|
||
|
||
## DOCX Invoice
|
||
|
||
**Tool:** `generate_invoice_docx`
|
||
**Package:** `@paperjsx/json-to-docx`
|
||
|
||
| Field | Type | Required | Default | Description |
|
||
|-------|------|----------|---------|-------------|
|
||
| `invoice_number` | string | yes | — | Invoice ID |
|
||
| `date` | string | yes | — | Invoice date |
|
||
| `due_date` | string | yes | — | Payment due date |
|
||
| `sender` | object | yes | — | `{ name, address, email?, phone?, tax_id? }` |
|
||
| `recipient` | object | yes | — | `{ name, address, email?, tax_id? }` |
|
||
| `items` | InvoiceItem[] | yes | — | Line items (min: 1) |
|
||
| `subtotal` | number | yes | — | Subtotal amount |
|
||
| `tax_rate` | number | no | — | Tax rate (decimal, e.g. 0.1 = 10%) |
|
||
| `tax_amount` | number | yes | — | Tax amount |
|
||
| `total` | number | yes | — | Total amount |
|
||
| `currency` | string | no | `"USD"` | ISO 4217 code |
|
||
| `notes` | string | no | — | Additional notes |
|
||
| `theme` | enum | no | `"corporate"` | `"corporate"`, `"modern"`, `"minimal"` |
|
||
| `page_size` | enum | no | `"a4"` | `"a4"`, `"letter"` |
|
||
|
||
**InvoiceItem:** `{ description: string, quantity: number, unit_price: number, amount: number }`
|