@statelyai/sdk 0.6.1 → 0.7.1

package/dist/sync.d.mts

@@ -1,5 +1,5 @@
 import { CreateProjectInput, ProjectData, StudioClient, StudioMachineRecord, XStateVersion } from "./studio.mjs";
-import { b as DigraphConfig, i as StatelyGraph } from "./graph-DpBGHZwl.mjs";
+import { b as DigraphConfig, i as StatelyGraph } from "./graph-zuNj3kfa.mjs";
 import { GraphDiff } from "@statelyai/graph";
 
 //#region src/sync.d.ts
@@ -52,8 +52,26 @@ interface PushSyncResult {
   machine: StudioMachineRecord<DigraphConfig>;
   outputPath?: string;
 }
+interface PushLocalMachineLinksResult {
+  sourcePath: string;
+  project: ProjectData;
+  created: Array<{
+    machineIndex: number;
+    machine: StudioMachineRecord<DigraphConfig>;
+  }>;
+  updated: Array<{
+    machineIndex: number;
+    machine: StudioMachineRecord<DigraphConfig>;
+  }>;
+  skipped: Array<{
+    machineIndex: number;
+    reason: string;
+  }>;
+  outputPath?: string;
+}
+declare function pushLocalMachineLinks(options: PushSyncOptions): Promise<PushLocalMachineLinksResult>;
 declare function planSync(options: PlanSyncOptions): Promise<SyncPlan>;
 declare function pullSync(options: PlanSyncOptions): Promise<PullSyncResult>;
 declare function pushSync(options: PushSyncOptions): Promise<PushSyncResult>;
 //#endregion
-export { PlanSyncOptions, PullSyncResult, PushSyncOptions, PushSyncProjectOptions, PushSyncResult, ResolvedSyncInput, SyncInputFormat, SyncPlan, SyncPlanSummary, planSync, pullSync, pushSync };
+export { PlanSyncOptions, PullSyncResult, PushLocalMachineLinksResult, PushSyncOptions, PushSyncProjectOptions, PushSyncResult, ResolvedSyncInput, SyncInputFormat, SyncPlan, SyncPlanSummary, planSync, pullSync, pushLocalMachineLinks, pushSync };

package/dist/sync.mjs

@@ -1,377 +1,5 @@
-import { createStatelyClient } from "./studio.mjs";
-import { d as upsertStatelyPragma, t as graphToXStateTS } from "./graphToXStateTS-Gzh0ZqbN.mjs";
-import { fromStudioMachine, toStudioMachine } from "./graph.mjs";
-import { getDiff, isEmptyDiff } from "@statelyai/graph";
-import fs from "node:fs/promises";
-import path from "node:path";
-import { execFile } from "node:child_process";
-import { promisify } from "node:util";
+import "./studio.mjs";
+import "./graphToXStateTS-Gzh0ZqbN.mjs";
+import { i as pushSync, n as pullSync, r as pushLocalMachineLinks, t as planSync } from "./sync-DLkTmSyA.mjs";
 
-//#region src/sync.ts
-const execFileAsync = promisify(execFile);
-function isUrl(value) {
-	try {
-		const url = new URL(value);
-		return url.protocol === "http:" || url.protocol === "https:";
-	} catch {
-		return false;
-	}
-}
-async function fileExists(filePath) {
-	try {
-		await fs.access(filePath);
-		return true;
-	} catch {
-		return false;
-	}
-}
-function parseGitHubRemote(remoteUrl) {
-	const httpsMatch = remoteUrl.match(/^https:\/\/github\.com\/([^/]+)\/([^/]+?)(?:\.git)?$/);
-	if (httpsMatch) {
-		const [, owner, repo] = httpsMatch;
-		if (!owner || !repo) return null;
-		return {
-			url: `https://github.com/${owner}/${repo}`,
-			owner,
-			repo
-		};
-	}
-	const sshMatch = remoteUrl.match(/^git@github\.com:([^/]+)\/([^/]+?)(?:\.git)?$/);
-	if (sshMatch) {
-		const [, owner, repo] = sshMatch;
-		if (!owner || !repo) return null;
-		return {
-			url: `https://github.com/${owner}/${repo}`,
-			owner,
-			repo
-		};
-	}
-	return null;
-}
-async function inferConnectedRepo(filePath, cwd) {
-	const workingDir = cwd ?? path.dirname(filePath);
-	try {
-		const [{ stdout: repoRootStdout }, { stdout: remoteStdout }, { stdout: branchStdout }, { stdout: treeShaStdout }] = await Promise.all([
-			execFileAsync("git", ["rev-parse", "--show-toplevel"], { cwd: workingDir }),
-			execFileAsync("git", [
-				"remote",
-				"get-url",
-				"origin"
-			], { cwd: workingDir }),
-			execFileAsync("git", ["branch", "--show-current"], { cwd: workingDir }),
-			execFileAsync("git", ["rev-parse", "HEAD"], { cwd: workingDir })
-		]);
-		const repoRoot = repoRootStdout.trim();
-		const remote = parseGitHubRemote(remoteStdout.trim());
-		const branch = branchStdout.trim();
-		const treeSha = treeShaStdout.trim();
-		if (!remote || !branch || !treeSha) return;
-		const relativePath = path.relative(repoRoot, filePath).replace(/\\/g, "/");
-		const relativeDir = path.dirname(relativePath).replace(/\\/g, "/");
-		const selectedPaths = relativePath && relativePath !== "." ? [relativePath] : [];
-		return {
-			...remote,
-			branch,
-			treeSha,
-			autoSync: false,
-			pathForNewFiles: relativeDir && relativeDir !== "." ? relativeDir : "src/stately-studio",
-			selectedPaths
-		};
-	} catch {
-		return;
-	}
-}
-function normalizeActions(value) {
-	if (value == null) return [];
-	return (Array.isArray(value) ? value : [value]).map((item) => {
-		if (typeof item === "string") return { type: item };
-		if (typeof item === "object" && item !== null && "type" in item) {
-			const type = item.type;
-			const params = "params" in item && typeof item.params === "object" && item.params ? item.params : void 0;
-			return {
-				type,
-				...params ? { params } : {}
-			};
-		}
-		return { type: String(item) };
-	});
-}
-function normalizeTags(value) {
-	if (!value) return [];
-	if (Array.isArray(value)) return value.map((tag) => String(tag));
-	return [String(value)];
-}
-function normalizeInvoke(value) {
-	if (!value) return [];
-	return (Array.isArray(value) ? value : [value]).map((invoke, index) => ({
-		src: invoke.src,
-		id: invoke.id ?? `invoke[${index}]`,
-		...invoke.input ? { input: invoke.input } : {}
-	}));
-}
-function resolveTargetId(sourceParentPath, target) {
-	if (!target) return;
-	if (target.startsWith("#")) {
-		const stripped = target.slice(1);
-		const machineIndex = stripped.indexOf(".");
-		if (machineIndex >= 0) return `(machine).${stripped.slice(machineIndex + 1)}`;
-		return `(machine).${stripped}`;
-	}
-	if (target.startsWith("(machine)")) return target;
-	if (target.includes(".")) return `(machine).${target}`;
-	return `${sourceParentPath}.${target}`;
-}
-function appendTransitionEdges(edges, sourceId, sourceParentPath, eventType, transition, edgeCounts) {
-	const transitions = Array.isArray(transition) ? transition : [transition];
-	for (const item of transitions) {
-		const normalized = typeof item === "string" ? { target: item } : item;
-		const targetId = resolveTargetId(sourceParentPath, Array.isArray(normalized.target) ? normalized.target[0] : normalized.target);
-		const groupKey = `${sourceId}:${eventType}`;
-		const index = edgeCounts.get(groupKey) ?? 0;
-		edgeCounts.set(groupKey, index + 1);
-		edges.push({
-			type: "edge",
-			id: `${sourceId}#${eventType}[${index}]`,
-			sourceId,
-			targetId: targetId ?? sourceId,
-			label: eventType,
-			data: {
-				eventType,
-				transitionType: normalized.reenter === true ? "reenter" : normalized.internal === true || !targetId ? "targetless" : "normal",
-				...normalized.guard ? { guard: typeof normalized.guard === "string" ? { type: normalized.guard } : {
-					type: normalized.guard.type,
-					...normalized.guard.params ? { params: normalized.guard.params } : {}
-				} } : {},
-				actions: normalizeActions(normalized.actions),
-				...normalized.description ? { description: normalized.description } : {}
-			}
-		});
-	}
-}
-function fromXStateConfig(config) {
-	const nodes = [];
-	const edges = [];
-	const edgeCounts = /* @__PURE__ */ new Map();
-	function visitNode(key, nodeConfig, parentId, parentPath) {
-		const nodeId = parentPath ? `${parentPath}.${key}` : "(machine)";
-		const currentPath = parentPath ? nodeId : "(machine)";
-		const initialId = nodeConfig.initial ? `${currentPath}.${nodeConfig.initial}` : void 0;
-		nodes.push({
-			type: "node",
-			id: nodeId,
-			parentId,
-			label: key,
-			...initialId ? { initialNodeId: initialId } : {},
-			data: {
-				key,
-				...nodeConfig.type ? { type: nodeConfig.type } : {},
-				...nodeConfig.history ? { history: nodeConfig.history } : {},
-				...initialId ? { initialId } : {},
-				entry: normalizeActions(nodeConfig.entry),
-				exit: normalizeActions(nodeConfig.exit),
-				invokes: normalizeInvoke(nodeConfig.invoke),
-				tags: normalizeTags(nodeConfig.tags),
-				...nodeConfig.description ? { description: nodeConfig.description } : {}
-			}
-		});
-		for (const [eventType, transition] of Object.entries(nodeConfig.on ?? {})) appendTransitionEdges(edges, nodeId, parentPath ?? "(machine)", eventType, transition, edgeCounts);
-		if (nodeConfig.always) appendTransitionEdges(edges, nodeId, parentPath ?? "(machine)", "", nodeConfig.always, edgeCounts);
-		for (const [childKey, childConfig] of Object.entries(nodeConfig.states ?? {})) visitNode(childKey, childConfig, nodeId, currentPath);
-	}
-	visitNode("(machine)", config, null, null);
-	return {
-		id: config.id ?? "machine",
-		nodes,
-		edges,
-		data: {}
-	};
-}
-async function resolveLocalFile(locator, options) {
-	const filePath = path.resolve(options.cwd ?? process.cwd(), locator);
-	const contents = await fs.readFile(filePath, "utf8");
-	const extension = path.extname(filePath).toLowerCase();
-	if (extension === ".ts" || extension === ".tsx" || extension === ".js" || extension === ".jsx") {
-		const config = (await (options.client ?? createStatelyClient({
-			apiKey: options.apiKey,
-			baseUrl: options.baseUrl,
-			fetch: options.fetch
-		})).code.extractMachines(contents)).machines[0]?.config;
-		if (!config) throw new Error(`No machines extracted from ${filePath}`);
-		return {
-			kind: "local-file",
-			locator: filePath,
-			format: "xstate",
-			graph: fromXStateConfig(config)
-		};
-	}
-	const parsed = JSON.parse(contents);
-	if ("rootNode" in parsed && "edges" in parsed) return {
-		kind: "local-file",
-		locator: filePath,
-		format: "digraph",
-		graph: fromStudioMachine(parsed)
-	};
-	if ("nodes" in parsed && "edges" in parsed) return {
-		kind: "local-file",
-		locator: filePath,
-		format: "graph",
-		graph: parsed
-	};
-	if ("states" in parsed) return {
-		kind: "local-file",
-		locator: filePath,
-		format: "xstate",
-		graph: fromXStateConfig(parsed)
-	};
-	throw new Error(`Unsupported local sync input: ${filePath}`);
-}
-function inferWritableTargetFormat(filePath) {
-	if (filePath.endsWith(".ts") || filePath.endsWith(".tsx") || filePath.endsWith(".js") || filePath.endsWith(".jsx")) return "xstate";
-	if (filePath.endsWith(".digraph.json")) return "digraph";
-	if (filePath.endsWith(".graph.json")) return "graph";
-	return null;
-}
-function serializeGraph(graph, format, options = {}) {
-	switch (format) {
-		case "digraph": return `${JSON.stringify(toStudioMachine(graph), null, 2)}\n`;
-		case "graph": return `${JSON.stringify(graph, null, 2)}\n`;
-		case "xstate": {
-			const source = graphToXStateTS(graph);
-			if (!options.remoteMachineId) return source;
-			return upsertStatelyPragma(source, options.remoteMachineId, options.targetPath ? { fileName: options.targetPath } : {});
-		}
-		default: {
-			const exhaustive = format;
-			throw new Error(`Unsupported sync output format: ${exhaustive}`);
-		}
-	}
-}
-async function resolveRemoteMachine(machineId, baseUrl, kind, locator, options) {
-	return {
-		kind,
-		locator,
-		format: "digraph",
-		graph: fromStudioMachine(await (options.client ?? createStatelyClient({
-			apiKey: options.apiKey,
-			baseUrl,
-			fetch: options.fetch
-		})).machines.get(machineId)),
-		remoteMachineId: machineId
-	};
-}
-async function resolveSyncInput(locator, options) {
-	if (await fileExists(path.resolve(options.cwd ?? process.cwd(), locator))) return resolveLocalFile(locator, options);
-	if (isUrl(locator)) {
-		const url = new URL(locator);
-		const machineId = url.pathname.split("/").filter(Boolean).at(-1);
-		if (!machineId) throw new Error(`Could not resolve machine ID from URL: ${locator}`);
-		return resolveRemoteMachine(machineId, url.origin, "studio-url", locator, options);
-	}
-	return resolveRemoteMachine(locator, options.baseUrl, "studio-machine-id", locator, options);
-}
-function summarizeDiff(diff) {
-	const nodeChanges = diff.nodes.added.length + diff.nodes.removed.length + diff.nodes.updated.length;
-	const edgeChanges = diff.edges.added.length + diff.edges.removed.length + diff.edges.updated.length;
-	return {
-		hasChanges: !isEmptyDiff(diff),
-		nodeChanges,
-		edgeChanges
-	};
-}
-async function planSync(options) {
-	const source = await resolveSyncInput(options.source, options);
-	const target = await resolveSyncInput(options.target, options);
-	const diff = getDiff(source.graph, target.graph);
-	return {
-		source,
-		target,
-		diff,
-		summary: summarizeDiff(diff),
-		warnings: []
-	};
-}
-async function pullSync(options) {
-	const source = await resolveSyncInput(options.source, options);
-	const outputPath = path.resolve(options.cwd ?? process.cwd(), options.target);
-	const fallbackFormat = inferWritableTargetFormat(outputPath);
-	let targetFormat = fallbackFormat;
-	if (await fileExists(outputPath)) try {
-		targetFormat = (await resolveLocalFile(options.target, options)).format;
-	} catch (error) {
-		if (!fallbackFormat) throw error;
-	}
-	if (!targetFormat) throw new Error(`Could not infer a writable target format from ${outputPath}. Use an existing digraph/graph file or a .digraph.json/.graph.json target.`);
-	const serialized = serializeGraph(source.graph, targetFormat, {
-		remoteMachineId: source.remoteMachineId,
-		targetPath: outputPath
-	});
-	await fs.writeFile(outputPath, serialized, "utf8");
-	return {
-		source,
-		target: {
-			kind: "local-file",
-			locator: outputPath,
-			format: targetFormat,
-			graph: source.graph
-		},
-		outputPath
-	};
-}
-function inferDefaultProjectName(sourcePath, repo) {
-	if (repo?.repo) return repo.repo;
-	const parentDir = path.basename(path.dirname(sourcePath));
-	if (parentDir && parentDir !== ".") return parentDir;
-	return path.basename(sourcePath, path.extname(sourcePath));
-}
-async function resolvePushProject(client, sourcePath, options) {
-	const explicitProject = options.project;
-	if (explicitProject?.projectVersionId) return client.projects.get(explicitProject.projectVersionId);
-	if (explicitProject?.projectId) return client.projects.get(explicitProject.projectId);
-	const inferredRepo = explicitProject?.repo ?? await inferConnectedRepo(sourcePath, options.cwd);
-	const projectInput = {
-		name: explicitProject?.name ?? inferDefaultProjectName(sourcePath, inferredRepo),
-		visibility: explicitProject?.visibility ?? "Private",
-		...explicitProject?.description ? { description: explicitProject.description } : {},
-		...explicitProject?.keywords ? { keywords: explicitProject.keywords } : {},
-		...inferredRepo ? { repo: inferredRepo } : {}
-	};
-	return client.projects.ensure(projectInput);
-}
-async function pushSync(options) {
-	const client = options.client ?? createStatelyClient({
-		apiKey: options.apiKey,
-		baseUrl: options.baseUrl,
-		fetch: options.fetch
-	});
-	const source = await resolveSyncInput(options.source, {
-		...options,
-		target: options.source
-	});
-	if (source.kind !== "local-file") throw new Error("pushSync currently requires a local source file.");
-	const sourcePath = source.locator;
-	const project = await resolvePushProject(client, sourcePath, options);
-	if (!project.projectVersionId) throw new Error("Resolved project is missing projectVersionId.");
-	const machine = await client.machines.create({
-		projectVersionId: project.projectVersionId,
-		definition: toStudioMachine(source.graph),
-		xstateVersion: options.xstateVersion ?? 5
-	});
-	let outputPath;
-	if (source.format === "xstate") {
-		const contents = await fs.readFile(sourcePath, "utf8");
-		const nextContents = upsertStatelyPragma(contents, machine.id, { fileName: sourcePath });
-		if (nextContents !== contents) {
-			await fs.writeFile(sourcePath, nextContents, "utf8");
-			outputPath = sourcePath;
-		}
-	}
-	return {
-		source,
-		project,
-		machine,
-		...outputPath ? { outputPath } : {}
-	};
-}
-
-//#endregion
-export { planSync, pullSync, pushSync };
+export { planSync, pullSync, pushLocalMachineLinks, pushSync };

package/dist/{transport-C0eTgNNu.mjs → transport-C8UTS3Fa.mjs}

@@ -1,7 +1,7 @@
 //#region src/clientUtils.ts
 const jsonResultFormats = new Set([
 	"digraph",
-	"json",
+	"xstate-json",
 	"xgraph"
 ]);
 function createRequestId() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statelyai/sdk",
-  "version": "0.6.1",
+  "version": "0.7.1",
   "license": "MIT",
   "bin": {
     "statelyai": "./dist/cli.mjs"
@@ -54,11 +54,14 @@
       "import": "./dist/assetStorage.mjs"
     },
     "./statelyai.schema.json": "./schemas/statelyai.schema.json",
-    "./schemas/statelyai.schema.json": "./schemas/statelyai.schema.json"
+    "./schemas/statelyai.schema.json": "./schemas/statelyai.schema.json",
+    "./xstate-json.schema.json": "./schemas/xstate-json.schema.json",
+    "./schemas/xstate-json.schema.json": "./schemas/xstate-json.schema.json"
   },
   "dependencies": {
     "@oclif/core": "^4.10.3",
     "@statelyai/graph": "^0.9.0",
+    "esbuild": "^0.27.0",
     "typescript": "^5.9.3",
     "xstate": "^5.0.0"
   },

package/schemas/statelyai.schema.json

@@ -54,7 +54,7 @@
       "enum": [
         "auto",
         "xstate",
-        "json",
+        "xstate-json",
         "xgraph",
         "digraph",
         "mermaid",

package/schemas/xstate-json.schema.json

@@ -0,0 +1,214 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://stately.ai/schemas/xstate-json.json",
+  "title": "XState JSON machine config",
+  "description": "Strict JSON subset of an XState machine config that can be passed to createMachine(config). Shorthand string forms are normalized to object and array forms.",
+  "$ref": "#/$defs/machineConfig",
+  "$defs": {
+    "jsonValue": {
+      "description": "Any JSON value.",
+      "oneOf": [
+        { "type": "null" },
+        { "type": "boolean" },
+        { "type": "number" },
+        { "type": "string" },
+        {
+          "type": "array",
+          "items": { "$ref": "#/$defs/jsonValue" }
+        },
+        {
+          "type": "object",
+          "additionalProperties": { "$ref": "#/$defs/jsonValue" }
+        }
+      ]
+    },
+    "jsonObject": {
+      "type": "object",
+      "additionalProperties": { "$ref": "#/$defs/jsonValue" }
+    },
+    "parameterizedObject": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type"],
+      "properties": {
+        "type": { "type": "string", "minLength": 1 },
+        "params": { "$ref": "#/$defs/jsonValue" }
+      }
+    },
+    "actionObject": {
+      "$ref": "#/$defs/parameterizedObject"
+    },
+    "guardObject": {
+      "$ref": "#/$defs/parameterizedObject"
+    },
+    "transitionObject": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "target": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "guard": { "$ref": "#/$defs/guardObject" },
+        "actions": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/actionObject" }
+        },
+        "reenter": { "type": "boolean" },
+        "meta": { "$ref": "#/$defs/jsonObject" },
+        "description": { "type": "string" }
+      }
+    },
+    "transitionArray": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/transitionObject" }
+    },
+    "transitionsByEvent": {
+      "type": "object",
+      "additionalProperties": { "$ref": "#/$defs/transitionArray" }
+    },
+    "invokeObject": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["src"],
+      "properties": {
+        "id": { "type": "string" },
+        "systemId": { "type": "string" },
+        "src": { "type": "string", "minLength": 1 },
+        "input": { "$ref": "#/$defs/jsonValue" },
+        "onDone": { "$ref": "#/$defs/transitionArray" },
+        "onError": { "$ref": "#/$defs/transitionArray" },
+        "onSnapshot": { "$ref": "#/$defs/transitionArray" }
+      }
+    },
+    "stateNodeConfig": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string" },
+        "type": {
+          "enum": ["atomic", "compound", "parallel", "final", "history"]
+        },
+        "history": {
+          "anyOf": [
+            { "enum": ["shallow", "deep"] },
+            { "type": "boolean" }
+          ]
+        },
+        "states": {
+          "type": "object",
+          "additionalProperties": { "$ref": "#/$defs/stateNodeConfig" }
+        },
+        "invoke": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/invokeObject" }
+        },
+        "on": { "$ref": "#/$defs/transitionsByEvent" },
+        "entry": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/actionObject" }
+        },
+        "exit": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/actionObject" }
+        },
+        "onDone": { "$ref": "#/$defs/transitionArray" },
+        "after": { "$ref": "#/$defs/transitionsByEvent" },
+        "always": { "$ref": "#/$defs/transitionArray" },
+        "meta": { "$ref": "#/$defs/jsonObject" },
+        "output": { "$ref": "#/$defs/jsonValue" },
+        "order": { "type": "number" },
+        "tags": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "description": { "type": "string" },
+        "target": { "type": "string" },
+        "initial": { "type": "string" }
+      }
+    },
+    "machineConfig": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string" },
+        "type": {
+          "enum": ["atomic", "compound", "parallel", "final", "history"]
+        },
+        "history": {
+          "anyOf": [
+            { "enum": ["shallow", "deep"] },
+            { "type": "boolean" }
+          ]
+        },
+        "states": {
+          "type": "object",
+          "additionalProperties": { "$ref": "#/$defs/stateNodeConfig" }
+        },
+        "invoke": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/invokeObject" }
+        },
+        "on": { "$ref": "#/$defs/transitionsByEvent" },
+        "entry": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/actionObject" }
+        },
+        "exit": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/actionObject" }
+        },
+        "onDone": { "$ref": "#/$defs/transitionArray" },
+        "after": { "$ref": "#/$defs/transitionsByEvent" },
+        "always": { "$ref": "#/$defs/transitionArray" },
+        "meta": { "$ref": "#/$defs/jsonObject" },
+        "output": { "$ref": "#/$defs/jsonValue" },
+        "order": { "type": "number" },
+        "tags": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "description": { "type": "string" },
+        "target": { "type": "string" },
+        "initial": { "type": "string" },
+        "schemas": { "$ref": "#/$defs/jsonValue" },
+        "version": { "type": "string" },
+        "context": { "$ref": "#/$defs/jsonObject" },
+        "options": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "maxIterations": { "type": "number" }
+          }
+        }
+      }
+    }
+  },
+  "examples": [
+    {
+      "id": "trafficLight",
+      "initial": "green",
+      "states": {
+        "green": {
+          "tags": ["go"],
+          "on": {
+            "TIMER": [
+              {
+                "target": ["yellow"],
+                "actions": [{ "type": "trackChange" }]
+              }
+            ]
+          }
+        },
+        "yellow": {
+          "on": {
+            "TIMER": [{ "target": ["red"] }]
+          }
+        },
+        "red": {
+          "type": "final"
+        }
+      }
+    }
+  ]
+}