JSON Schema Reference

Complete specification for Privacy Sketch's JSON format. Use this reference to generate diagrams programmatically or via LLM.

LLM-Optimized This documentation is designed for both human developers and Large Language Models. The JSON format is deliberately simple and self-documenting.

Overview

Privacy Sketch diagrams are defined as JSON objects containing an elements array. Each element represents a shape, text, line, or icon on the canvas.

{
  "elements": [
    { /* element 1 */ },
    { /* element 2 */ },
    // ... more elements
  ]
}

Root Structure

The root JSON object structure:

Property Type Required Description
elements array Yes Array of element objects to render

Element Base Properties

All elements share these common properties:

Property Type Required Default Description
type string Yes - Element type (see Shape Types)
id string Yes - Unique identifier for the element
x number No 0 X coordinate (left position)
y number No 0 Y coordinate (top position)
w number No 100 Width in pixels
h number No 100 Height in pixels
angle number No 0 Rotation in degrees (clockwise)
options object No {} Styling options (see Options)

Shape Types

The type property determines what kind of element to render. Here are all available types:

Basic Shapes

Type Description Extra Properties
rectangle Rectangle/square borderRadius: corner rounding (0-50)
ellipse Ellipse/circle -
diamond Diamond (rotated square) -
triangle Triangle -

Geometric Shapes

Type Description Extra Properties
star Star shape points: 3-12, innerRadius: 0.1-0.9
heart Heart shape -
hexagon 6-sided polygon -
pentagon 5-sided polygon -
cloud Cloud shape -
cylinder Cylinder (database) -
cube 3D cube -

Annotations

Type Description
speechBubble Speech bubble with pointer
thoughtBubble Thought bubble with dots
callout Callout box
stickyNote Post-it style note
banner Ribbon banner

Flowchart Symbols

Type Symbol Use For
rectangle Process Actions, steps
diamond Decision Yes/No conditions
ellipse Terminal Start/End
parallelogram Data Input/Output
cylinder Database Storage
document Document Reports, files

Text Element

The text type renders text on the canvas.

Property Type Default Description
text string "" Text content (use \n for newlines)
fontSize number 20 Font size in pixels
fontWeight string "normal" "normal" or "bold"
fontStyle string "normal" "normal" or "italic"
align string "left" "left", "center", or "right"
Text Color For text elements, set the color using options.stroke, not options.fill. 
{
  "type": "text",
  "id": "title",
  "x": 100,
  "y": 100,
  "w": 200,
  "h": 30,
  "text": "Hello World",
  "fontSize": 24,
  "fontWeight": "bold",
  "align": "center",
  "options": {
    "stroke": "#1e293b"
  }
}

Lines & Arrows

Lines and arrows connect points on the canvas.

Type Description
line Simple line (no arrowhead)
arrow Line with arrowhead at end
bidirectionalArrow Arrows at both ends

Position Properties for Lines

For lines, x and y are the start point. w and h define the vector to the end point:

// Horizontal arrow from (100,200) to (300,200)
{
  "type": "arrow",
  "id": "arrow-1",
  "x": 100,
  "y": 200,
  "w": 200,
  "h": 1,
  "options": {
    "stroke": "#374151",
    "strokeWidth": 2
  }
}

Options Object (Styling)

The options object controls the visual appearance of elements:

Property Type Default Description
fill string "transparent" Fill color (hex format, e.g., "#dbeafe")
stroke string "#000000" Stroke/border color (hex format)
strokeWidth number 2 Stroke thickness in pixels (1-10)
roughness number 1.5 Sketch effect (0=smooth, 3=very rough)
bowing number 1 Line curvature (0-5)
fillStyle string "hachure" Fill pattern (see Fill Styles)
fillWeight number 0.5 Hachure line thickness
hachureGap number 4 Gap between hachure lines
seed number random Random seed for consistent rendering

Fill Styles

The fillStyle option controls how shapes are filled:

Value Description
"solid" Solid color fill
"hachure" Diagonal line pattern (default)
"cross-hatch" Cross-hatched lines
"zigzag" Zigzag pattern
"dots" Dot pattern
"dashed" Dashed lines
"zigzag-line" Zigzag line pattern
Solid Fills for Clean Look For cleaner, more professional diagrams, use "fillStyle": "solid" with lower "roughness" values.

Icons (Tabler Icons)

Use the tablerIcon type to add icons from the 6,000+ Tabler icon library:

Property Type Description
iconName string Icon name (e.g., "user", "star", "check")
iconStyle string "outline" or "filled" 
{
  "type": "tablerIcon",
  "id": "icon-1",
  "x": 100,
  "y": 100,
  "w": 48,
  "h": 48,
  "iconName": "check",
  "iconStyle": "outline",
  "options": {
    "stroke": "#22c55e"
  }
}

Complete Example: Card with Text

{
  "elements": [
    {
      "type": "rectangle",
      "id": "card",
      "x": 50,
      "y": 50,
      "w": 240,
      "h": 140,
      "borderRadius": 12,
      "options": {
        "fill": "#dbeafe",
        "stroke": "#3b82f6",
        "strokeWidth": 3,
        "roughness": 1.5,
        "fillStyle": "solid"
      }
    },
    {
      "type": "text",
      "id": "title",
      "x": 60,
      "y": 80,
      "w": 220,
      "h": 30,
      "text": "My First Card",
      "fontSize": 20,
      "fontWeight": "bold",
      "align": "center",
      "options": {
        "stroke": "#1e40af"
      }
    },
    {
      "type": "text",
      "id": "subtitle",
      "x": 60,
      "y": 120,
      "w": 220,
      "h": 24,
      "text": "A simple hand-drawn card",
      "fontSize": 14,
      "align": "center",
      "options": {
        "stroke": "#64748b"
      }
    }
  ]
}

Tips for LLM Diagram Generation

When generating diagrams with AI, follow these guidelines:

1. Always include required properties

// Every element MUST have type and id
{
  "type": "rectangle",  // Required
  "id": "unique-id",    // Required, must be unique
  ...
}

2. Use a consistent coordinate system

3. Use recommended color pairings

// For shapes: light fill + dark stroke
{
  "fill": "#dbeafe",    // blue.100 (light)
  "stroke": "#3b82f6"   // blue.500 (saturated)
}

// For text: use stroke for color
{
  "stroke": "#1e293b"   // slate.800 (dark)
}

4. Layer elements correctly

Elements render in array order. Place backgrounds first, then shapes, then text:

{
  "elements": [
    { /* background rectangle - rendered first */ },
    { /* main shapes - rendered second */ },
    { /* text labels - rendered last (on top) */ }
  ]
}

5. Common patterns

📦 Card Pattern

Rectangle + centered text. Use borderRadius: 12 for modern look.

➡️ Flow Connection

Arrow between two shapes. Set h: 1 for horizontal, w: 1 for vertical.

📅 Timeline

Vertical rectangle spine + circle nodes + text cards offset to the side.