1# Excalidraw JSON Schema Reference
2 
3This document describes the structure of Excalidraw `.excalidraw` files for diagram generation.
4 
5## Top-Level Structure
6 
7```typescript
8interface ExcalidrawFile {
9  type: "excalidraw";
10  version: number;           // Always 2
11  source: string;            // "https://excalidraw.com"
12  elements: ExcalidrawElement[];
13  appState: AppState;
14  files: Record<string, any>; // Usually empty {}
15}
16```
17 
18## AppState
19 
20```typescript
21interface AppState {
22  viewBackgroundColor: string; // Hex color, e.g., "#ffffff"
23  gridSize: number;            // Typically 20
24}
25```
26 
27## ExcalidrawElement Base Properties
28 
29All elements share these common properties:
30 
31```typescript
32interface BaseElement {
33  id: string;                  // Unique identifier
34  type: ElementType;           // See Element Types below
35  x: number;                   // X coordinate (pixels from top-left)
36  y: number;                   // Y coordinate (pixels from top-left)
37  width: number;               // Width in pixels
38  height: number;              // Height in pixels
39  angle: number;               // Rotation angle in radians (usually 0)
40  strokeColor: string;         // Hex color, e.g., "#1e1e1e"
41  backgroundColor: string;     // Hex color or "transparent"
42  fillStyle: "solid" | "hachure" | "cross-hatch";
43  strokeWidth: number;         // 1-4 typically
44  strokeStyle: "solid" | "dashed" | "dotted";
45  roughness: number;           // 0-2, controls hand-drawn effect (1 = default)
46  opacity: number;             // 0-100
47  groupIds: string[];          // IDs of groups this element belongs to
48  frameId: null;               // Usually null
49  index: string;               // Stacking order identifier
50  roundness: Roundness | null;
51  seed: number;                // Random seed for deterministic rendering
52  version: number;             // Element version (increment on edit)
53  versionNonce: number;        // Random number changed on edit
54  isDeleted: boolean;          // Should be false
55  boundElements: any;          // Usually null
56  updated: number;             // Timestamp in milliseconds
57  link: null;                  // External link (usually null)
58  locked: boolean;             // Whether element is locked
59}
60```
61 
62## Element Types
63 
64### Rectangle
65 
66```typescript
67interface RectangleElement extends BaseElement {
68  type: "rectangle";
69  roundness: { type: 3 };      // 3 = rounded corners
70  text?: string;               // Optional text inside
71  fontSize?: number;           // Font size (16-32 typical)
72  fontFamily?: number;         // 1 = Virgil, 2 = Helvetica, 3 = Cascadia
73  textAlign?: "left" | "center" | "right";
74  verticalAlign?: "top" | "middle" | "bottom";
75}
76```
77 
78**Example:**
79```json
80{
81  "id": "rect1",
82  "type": "rectangle",
83  "x": 100,
84  "y": 100,
85  "width": 200,
86  "height": 100,
87  "strokeColor": "#1e1e1e",
88  "backgroundColor": "#a5d8ff",
89  "text": "My Box",
90  "fontSize": 20,
91  "textAlign": "center",
92  "verticalAlign": "middle",
93  "roundness": { "type": 3 }
94}
95```
96 
97### Ellipse
98 
99```typescript
100interface EllipseElement extends BaseElement {
101  type: "ellipse";
102  text?: string;
103  fontSize?: number;
104  fontFamily?: number;
105  textAlign?: "left" | "center" | "right";
106  verticalAlign?: "top" | "middle" | "bottom";
107}
108```
109 
110### Diamond
111 
112```typescript
113interface DiamondElement extends BaseElement {
114  type: "diamond";
115  text?: string;
116  fontSize?: number;
117  fontFamily?: number;
118  textAlign?: "left" | "center" | "right";
119  verticalAlign?: "top" | "middle" | "bottom";
120}
121```
122 
123### Arrow
124 
125```typescript
126interface ArrowElement extends BaseElement {
127  type: "arrow";
128  points: [number, number][];  // Array of [x, y] coordinates relative to element
129  startBinding: Binding | null;
130  endBinding: Binding | null;
131  roundness: { type: 2 };      // 2 = curved arrow
132}
133```
134 
135**Example:**
136```json
137{
138  "id": "arrow1",
139  "type": "arrow",
140  "x": 100,
141  "y": 100,
142  "width": 200,
143  "height": 0,
144  "points": [
145    [0, 0],
146    [200, 0]
147  ],
148  "roundness": { "type": 2 },
149  "startBinding": null,
150  "endBinding": null
151}
152```
153 
154**Points explanation:**
155- First point `[0, 0]` is relative to `(x, y)`
156- Subsequent points are relative to the first point
157- For straight horizontal arrow: `[[0, 0], [width, 0]]`
158- For straight vertical arrow: `[[0, 0], [0, height]]`
159 
160### Line
161 
162```typescript
163interface LineElement extends BaseElement {
164  type: "line";
165  points: [number, number][];
166  startBinding: Binding | null;
167  endBinding: Binding | null;
168  roundness: { type: 2 } | null;
169}
170```
171 
172### Text
173 
174```typescript
175interface TextElement extends BaseElement {
176  type: "text";
177  text: string;
178  fontSize: number;
179  fontFamily: number;          // 1-3
180  textAlign: "left" | "center" | "right";
181  verticalAlign: "top" | "middle" | "bottom";
182  roundness: null;             // Text has no roundness
183}
184```
185 
186**Example:**
187```json
188{
189  "id": "text1",
190  "type": "text",
191  "x": 100,
192  "y": 100,
193  "width": 150,
194  "height": 25,
195  "text": "Hello World",
196  "fontSize": 20,
197  "fontFamily": 1,
198  "textAlign": "left",
199  "verticalAlign": "top",
200  "roundness": null
201}
202```
203 
204**Width/Height calculation:**
205- Width ≈ `text.length * fontSize * 0.6`
206- Height ≈ `fontSize * 1.2 * numberOfLines`
207 
208## Bindings
209 
210Bindings connect arrows to shapes:
211 
212```typescript
213interface Binding {
214  elementId: string;           // ID of bound element
215  focus: number;               // -1 to 1, position along edge
216  gap: number;                 // Distance from element edge
217}
218```
219 
220## Common Colors
221 
222| Color Name | Hex Code | Use Case |
223|------------|----------|----------|
224| Black | `#1e1e1e` | Default stroke |
225| Light Blue | `#a5d8ff` | Primary entities |
226| Light Green | `#b2f2bb` | Process steps |
227| Yellow | `#ffd43b` | Important/Central |
228| Light Red | `#ffc9c9` | Warnings/Errors |
229| Cyan | `#96f2d7` | Secondary items |
230| Transparent | `transparent` | No fill |
231| White | `#ffffff` | Background |
232 
233## ID Generation
234 
235IDs should be unique strings. Common patterns:
236 
237```javascript
238// Timestamp-based
239const id = Date.now().toString(36) + Math.random().toString(36).substr(2);
240 
241// Sequential
242const id = "element-" + counter++;
243 
244// Descriptive
245const id = "step-1", "entity-user", "arrow-1-to-2";
246```
247 
248## Seed Generation
249 
250Seeds are used for deterministic randomness in hand-drawn effect:
251 
252```javascript
253const seed = Math.floor(Math.random() * 2147483647);
254```
255 
256## Version and VersionNonce
257 
258```javascript
259const version = 1;  // Increment when element is edited
260const versionNonce = Math.floor(Math.random() * 2147483647);
261```
262 
263## Coordinate System
264 
265- Origin `(0, 0)` is top-left corner
266- X increases to the right
267- Y increases downward
268- All units are in pixels
269 
270## Recommended Spacing
271 
272| Context | Spacing |
273|---------|---------|
274| Horizontal gap between elements | 200-300px |
275| Vertical gap between rows | 100-150px |
276| Minimum margin from edge | 50px |
277| Arrow-to-box clearance | 20-30px |
278 
279## Font Families
280 
281| ID | Name | Description |
282|----|------|-------------|
283| 1 | Virgil | Hand-drawn style (default) |
284| 2 | Helvetica | Clean sans-serif |
285| 3 | Cascadia | Monospace |
286 
287## Validation Rules
288 
289✅ **Required:**
290- All IDs must be unique
291- `type` must match actual element type
292- `version` must be an integer ≥ 1
293- `opacity` must be 0-100
294 
295⚠️ **Recommended:**
296- Keep `roughness` at 1 for consistency
297- Use `strokeWidth` of 2 for clarity
298- Set `isDeleted` to `false`
299- Set `locked` to `false`
300- Keep `frameId`, `boundElements`, `link` as `null`
301 
302## Complete Minimal Example
303 
304```json
305{
306  "type": "excalidraw",
307  "version": 2,
308  "source": "https://excalidraw.com",
309  "elements": [
310    {
311      "id": "box1",
312      "type": "rectangle",
313      "x": 100,
314      "y": 100,
315      "width": 200,
316      "height": 100,
317      "angle": 0,
318      "strokeColor": "#1e1e1e",
319      "backgroundColor": "#a5d8ff",
320      "fillStyle": "solid",
321      "strokeWidth": 2,
322      "strokeStyle": "solid",
323      "roughness": 1,
324      "opacity": 100,
325      "groupIds": [],
326      "frameId": null,
327      "index": "a0",
328      "roundness": { "type": 3 },
329      "seed": 1234567890,
330      "version": 1,
331      "versionNonce": 987654321,
332      "isDeleted": false,
333      "boundElements": null,
334      "updated": 1706659200000,
335      "link": null,
336      "locked": false,
337      "text": "Hello",
338      "fontSize": 20,
339      "fontFamily": 1,
340      "textAlign": "center",
341      "verticalAlign": "middle"
342    }
343  ],
344  "appState": {
345    "viewBackgroundColor": "#ffffff",
346    "gridSize": 20
347  },
348  "files": {}
349}
350```
351