JSON Canvas Spec (2024)

Version 1.0 — 2024-03-11

The top level of JSON Canvas contains two arrays:

nodes

(optional, array of nodes)edges

(optional, array of edges)Nodes are objects within the canvas. Nodes may be text, files, links, or groups.

Nodes are placed in the array in ascending order by z-index. The first node in the array should be displayed below all other nodes, and the last node in the array should be displayed on top of all other nodes.

All nodes include the following attributes:

id

(required, string) is a unique ID for the node.type

(required, string) is the node type. text

file

link

group

x

(required, integer) is the x

position of the node in pixels.y

(required, integer) is the y

position of the node in pixels.width

(required, integer) is the width of the node in pixels.height

(required, integer) is the height of the node in pixels.color

(optional, canvasColor

) is the color of the node, see the Color section.Text type nodes store text. Along with generic node attributes, text nodes include the following attribute:

text

(required, string) in plain text with Markdown syntax.File type nodes reference other files or attachments, such as images, videos, etc. Along with generic node attributes, file nodes include the following attributes:

file

(required, string) is the path to the file within the system.subpath

(optional, string) is a subpath that may link to a heading or a block. Always starts with a #

.Link type nodes reference a URL. Along with generic node attributes, link nodes include the following attribute:

url

(required, string)Group type nodes are used as a visual container for nodes within it. Along with generic node attributes, group nodes include the following attributes:

label

(optional, string) is a text label for the group.background

(optional, string) is the path to the background image.backgroundStyle

(optional, string) is the rendering style of the background image. Valid values: cover

fills the entire width and height of the node.ratio

maintains the aspect ratio of the background image.repeat

repeats the image as a pattern in both x/y directions.Edges are lines that connect one node to another.

id

(required, string) is a unique ID for the edge.fromNode

(required, string) is the node id

where the connection starts.fromSide

(optional, string) is the side where this edge starts. Valid values: top

right

bottom

left

fromEnd

(optional, string) is the shape of the endpoint at the edge start. Defaults to none

if not specified. Valid values: none

arrow

toNode

(required, string) is the node id

where the connection ends.toSide

(optional, string) is the side where this edge ends. Valid values: top

right

bottom

left

toEnd

(optional, string) is the shape of the endpoint at the edge end. Defaults to arrow

if not specified. Valid values: none

arrow

color

(optional, canvasColor

) is the color of the line, see the Color section.label

(optional, string) is a text label for the edge.The canvasColor

type is used to encode color data for nodes and edges. Colors attributes expect a string. Colors can be specified in hex format e.g. "#FF0000"

, or using one of the preset colors, e.g. "1"

for red. Six preset colors exist, mapped to the following numbers:

"1"

red"2"

orange"3"

yellow"4"

green"5"

cyan"6"

purpleSpecific values for the preset colors are intentionally not defined so that applications can tailor the presets to their specific brand colors or color scheme.