JSON Serialization

Relevant source files

• packages/excalidraw/actions/actionBoundText.tsx
• packages/excalidraw/clipboard.ts
• packages/excalidraw/data/blob.ts
• packages/excalidraw/data/filesystem.ts
• packages/excalidraw/data/index.ts
• packages/excalidraw/data/json.ts
• packages/excalidraw/data/restore.ts
• packages/excalidraw/fonts/Fonts.ts
• packages/excalidraw/tests/helpers/api.ts
• packages/excalidraw/tests/helpers/mocks.ts
• packages/excalidraw/tests/image.test.tsx

This document covers the JSON serialization and deserialization system in Excalidraw. It explains how drawing data is converted to and from the .excalidraw file format, including the structure of the JSON schema, serialization functions, and validation logic.

For information about data restoration and migration from legacy formats, see Data Restoration and Migration. For clipboard-specific serialization, see Clipboard Operations. For export to PNG/SVG with embedded metadata, see Export System.

File Format Structure

The .excalidraw file format is a JSON structure that stores the complete drawing state. The format includes elements, application state, binary file references, and metadata.

Sources: packages/excalidraw/data/json.ts50-76 packages/excalidraw/data/types.ts

JSON Schema

The root object follows the ExportedDataState type:

Field	Type	Required	Description
type	"excalidraw"	Yes	Identifies the data format
version	number	Yes	Format version (VERSIONS.excalidraw)
source	string	Yes	Origin URL (e.g., "https://excalidraw.com")
elements	ExcalidrawElement[]	Yes	Array of drawing elements
appState	Partial<AppState>	No	Application state snapshot
files	BinaryFiles	No	Binary file data (images), only in local files

Sources: packages/excalidraw/data/json.ts50-76

Serialization Flow

Sources: packages/excalidraw/data/json.ts50-76

Core Serialization Functions

serializeAsJSON

The primary serialization function that converts scene data to a JSON string. It supports two serialization contexts: "local" for user-facing files and "database" for backend storage.

The function performs different cleaning operations based on the serialization context:

Context	Element Cleaning	AppState Cleaning	Files Included
"local"	clearElementsForExport()	cleanAppStateForExport()	Filtered by usage
"database"	clearElementsForDatabase()	clearAppStateForDatabase()	No (undefined)

Sources: packages/excalidraw/data/json.ts50-76

File Filtering

The filterOutDeletedFiles function strips out binary files that are only referenced by deleted elements, reducing file size:

Sources: packages/excalidraw/data/json.ts32-48

saveAsJSON

High-level function that serializes and saves the scene to a file using the File System API:

The function:

1. Calls serializeAsJSON() with "local" context
2. Creates a Blob with MIME type MIME_TYPES.excalidraw
3. Invokes fileSave() with .excalidraw extension
4. Returns the FileSystemHandle for future saves

Sources: packages/excalidraw/data/json.ts78-99

loadFromJSON

Counterpart to saveAsJSON that loads scene data from a file:

The function:

1. Opens file dialog via fileOpen()
2. Delegates to loadFromBlob() for parsing
3. Returns restored elements, appState, and files

Sources: packages/excalidraw/data/json.ts101-112

Validation Functions

isValidExcalidrawData

Type guard that validates if parsed JSON conforms to the expected schema:

Sources: packages/excalidraw/data/json.ts114-125

isValidLibrary

Validates library file format (.excalidrawlib files):

Checks for:

• Object type
• Correct type field ("excalidrawLibrary")
• Valid version (1 or 2)

Sources: packages/excalidraw/data/json.ts127-134

Clipboard Serialization

The clipboard system uses a specialized serialization format for copy/paste operations:

The serializeAsClipboardJSON function handles special cases:

• Frame handling: Removes frameId from elements whose containing frame is not also being copied
• File filtering: Only includes files referenced by image elements in the selection
• Deep copying: Creates deep copies of elements when modifying properties

Sources: packages/excalidraw/clipboard.ts150-200

Clipboard JSON Structure

Field	Type	Description
type	"excalidrawClipboard" or "excalidrawClipboardWithAPI"	Clipboard format identifier
elements	NonDeletedExcalidrawElement[]	Only non-deleted elements
files	BinaryFiles (optional)	Image file data if present

The "excalidrawClipboardWithAPI" type indicates programmatic clipboard access (via API) versus user clipboard operations.

Sources: packages/excalidraw/clipboard.ts44-48 packages/excalidraw/clipboard.ts150-200

Library Serialization

Libraries use a separate format for storing reusable element collections:

serializeLibraryAsJSON

Library File Format

Field	Type	Description
type	"excalidrawLibrary"	Library format identifier
version	1 or 2	Library format version
source	string	Origin URL
libraryItems	LibraryItem[]	Array of library items

Each LibraryItem contains:

• id: Unique identifier
• status: "published" or "unpublished"
• elements: Array of elements in the library item
• created: Timestamp

Sources: packages/excalidraw/data/json.ts136-144 packages/excalidraw/data/restore.ts831-873

Data Flow Through Serialization Pipeline

Sources: packages/excalidraw/data/json.ts50-99

Serialization Contexts

Local Context

Used for user-facing file operations (save, load, export):

• Element cleaning: clearElementsForExport() removes internal properties like lastCommittedPoint
• AppState cleaning: cleanAppStateForExport() removes ephemeral UI state
• Files: Includes filtered binary files
• Formatting: Pretty-printed with 2-space indentation

Database Context

Used for backend persistence and collaboration:

• Element cleaning: clearElementsForDatabase() performs more aggressive cleanup
• AppState cleaning: clearAppStateForDatabase() removes more properties
• Files: Excluded (stored separately in binary format)
• Formatting: Pretty-printed with 2-space indentation

Sources: packages/excalidraw/data/json.ts50-76

Integration with Other Systems

PNG Export with Metadata

The exportCanvas() function embeds serialized scene data into PNG files when exportEmbedScene is enabled:

This allows users to import PNG files back into Excalidraw with full scene restoration.

Sources: packages/excalidraw/data/index.ts170-182

Restoration Flow

Deserialization uses the restore() function from the restoration module:

1. Parse JSON with JSON.parse()
2. Validate with isValidExcalidrawData()
3. Pass to restore() which calls:
   • restoreElements() for element migration
   • restoreAppState() for state migration
4. Return RestoredDataState

Sources: packages/excalidraw/data/blob.ts135-195 packages/excalidraw/data/restore.ts808-829

Constants and Type Definitions

Export Data Types

MIME Types

Sources: packages/excalidraw/data/json.ts1-7