SketchAPI.Document

The SketchAPI.Document JSON format outlines everything about your documents, like layers, vector data, metadata, configuration, permissions, and template connections.

Note: You can use a SketchAPI.Document as a template by linking to its ID. This way, you can create a chain of connected documents where each document can link back to its parent template.

Table of Contents

• SketchAPI.Document
• ⭐️ Example
• 🕊️ Migration to v2024.11.04

---

SketchAPI.Document

namespace SketchAPI {
	export interface Document {
		/** API version identifier (2024.10.26.10) */
		sketchApi: string;

		/** Ancestry of the document (original, fork1, fork2) */
		ancestry: string[];
		/** Unique sketch identifier (UUID) */
		id: string;

		/** Creation timestamp (2024-10-26T10:00:00Z) */
		dateCreated: string;
		/** Last update timestamp (2024-11-05T12:00:00Z) */
		dateUpdated: string;
		/** Document version identifier (checkpoint-1) */
		version: string;

		/** Display name */
		name: string;
		/** Content purpose and description */
		description: string;
		/** Document metadata and tagging */
		metadata: {
			/** User-defined fields... */
			[key: string]: any;
		};

		/** Sketch content layers */
		layers: SketchLayer[];

		/** Page dimensions */
		pages: {
			/** Width in pixels */
			width: number;
			/** Height in pixels */
			height: number;
		}[];

		/** Document configuration */
		settings: {
			/** Canvas width in pixels */
			width: number;
			/** Canvas height in pixels */
			height: number;
			/** Measurement units (px, mm, in) */
			units: string;
			/** Export DPI resolution */
			exportDPI: number;
			/** Export file type (png, jpg, svg) */
			exportFormat: string;
			/** Export quality (0-1) */
			exportQuality: number;

			/** Clipping path configuration */
			clipPath: {
				/** Enable/disable clipping */
				enabled: boolean;
				/** Path styling */
				style: {
					/** Stroke color value */
					strokeStyle: string;
					/** Stroke width value */
					lineWidth: number;
				};
			};

			/** Surface rendering settings */
			surface: {
				/** Blend mode (normal, multiply, screen) */
				blend: string;
				/** Drawing method (fill, stroke, pattern) */
				method: string;
				/** Surface opacity (0-1) */
				opacity: number;
				/** Surface type (pattern, gradient) */
				type: string;
			};
		};

		/** Access control settings */
		sharing: {
			/** Access scope ID (public, user123) */
			id: string;
			/** Edit permission flag */
			canEdit: boolean;
			/** Fork permission flag */
			canFork: boolean;
			/** View permission flag */
			canView: boolean;
		}[];

		/** Tags for the document */
		tags: string[];

		/** Template configuration */
		template: {
			/** Template identifier */
			id: string;
			/** Template version */
			version: number;
			/** Template metadata */
			metadata: {
				/** User-defined fields... */
				[key: string]: any;
			};
		} | null;
	}
}

---

⭐️ Example

{
	// TODO moved from `json.version`
	"sketchApi": "2024.10.26.10",
	// TODO added
	"version": "checkpoint-1",
	"id": "sketch-UUID",
	// TODO moved from `json.name`
	"name": "My Homework Assignment",
	// TODO moved from `json.description`
	"description": "Draw a picture of your favorite animal.",
	// TODO added
	"dateCreated": "2024-10-26T10:00:00Z",
	// TODO added
	"dateUpdated": "2024-10-30T08:30:00Z",

	// TODO added
	"ancestry": [
		"originalSketchUUID",
		"fork1UUID",
		"fork2UUID"
	],

	// TODO added
	"template": {
		"id": "UUID",
		"version": 2,
		"metadata": {
			"creatorName": "Teacher Name",
			"intendedAudience": "Beginner artists",
			"usageGuidelines": "This template is for practice purposes.",
			"license": "Creative Commons"
		}
	},

	// TODO added protected metadata key
	"sharing": [
		{
			"id": "public",
			"canEdit": false,
			"canFork": true,
			"canView": true
		},
		{
			"id": "user123",
			"canEdit": true,
			"canFork": true,
			"canView": true
		}
	],

	// TODO moved from `json.metadata`
	"metadata": {},

	"layers": [
		{
			"id": "layer1",
			"type": "rectangle",
			"editable": false,
			"bbox": {
				"x": 0,
				"y": 0,
				"width": 1504,
				"height": 1013
			},
			"fill": {
				"color": "#cef28f",
				"opacity": 1
			}
		}
	],

	// TODO move from `json.pages`
	"pages": [
		{
			"width": 1504,
			"height": 1013
		}
	],

	// TODO added
	"tags": [
		"classwork",
		"art"
	],

	// TODO moved from `json.config`
	"settings": {
		"width": 1504,
		"height": 1013,
		"units": "px",
		"exportDPI": 72,
		"exportFormat": "png",
		"exportQuality": 0.95,
		"surface": {
			"blend": "normal",
			"method": "fill",
			"opacity": 1,
			"type": "pattern"
		},
		"clipPath": {
			"enabled": true,
			"style": {
				"strokeStyle": "black",
				"lineWidth": 1
			}
		}
	}
}

---

🕊️ Migration to v2024.11.04

• Write JSONPatch
• Reference new properties in SketchAPI

Moved properties

• root.sketchApi ← root.version
• root.description ← root.config.description
• root.id ← root.config.uuid
• root.metadata ← root.config.metadata
  • Data owned by the creator of the document.
• root.name ← root.config.name
• root.pages ← root.config.pages
• root.settings ← root.config

Added properties

• root.dateCreated = “2024-10-26T10:00:00Z”
• root.dateUpdated = “2024-10-30T08:30:00Z”
• root.version = “checkpoint-1”
  • Version of the Document—increments with each save.
  • Allow users to set UNDO/REDO to be based on individual CHANGES or document SAVES.
• root.ancestry = ["originalSketchUUID", "fork1UUID", "fork2UUID"]
  • When duplicating a document, in the new document, append the original document’s ID to the ancestry array.
• root.sharing
  • Sharing settings for the document.
• root.tags = ["branding", "social", "template"]
  • Tags show up in the Open Document pane, for searching and filtering results.
• root.template
  • Allow creators/teachers to create a template:
  • id = UUID
  • version = 1
    • Allow them to prompt their users to update when template changes are made.
  • metadata
    • Data owned by the creator of the template.