jsoncanvas-desktop/spec/spec.md

Canvas Spec

Based on JSON Canvas 1.0 — 2024-03-11

The file format jsoncanvas-desktop reads and writes, in full.

It is JSON Canvas 1.0 with a small number of additions. Everything the original defines is implemented, unchanged and under the same names, and the sections below follow its wording. Attributes and rules this editor adds are marked (addition) and are collected, with the reasoning behind them, in extensions.md.

Files use the .canvas extension.

Top level

The top level of JSON Canvas contains two arrays:

• nodes (optional, array of nodes)
• edges (optional, array of edges)

Nodes

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.

Generic node

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

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

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

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

• url (required, string)
• label (optional, string) is the text displayed for the node in place of its URL. A label that is empty or only whitespace is treated as no label. (addition)

Group type nodes

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

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.

Color

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" purple

Specific values for the preset colors are intentionally not defined so that applications can tailor the presets to their specific brand colors or color scheme. This editor uses one set of six shades for both of its themes, and blends them into a node's fill with more of the shade in the dark theme than in the light one.

Unrecognised data (addition)

Anything in the file this spec does not describe is kept as it was:

• unknown top-level keys,
• unknown attributes on a node or an edge,
• nodes whose type is none of the four above — the whole node is kept, and the canvas displays a placeholder in its place.

Unrecognised data is written back unchanged, after the attributes this spec defines. This makes a file written by another application survive a load and save untouched.

Reading (addition)

A file that does not follow this spec exactly is still read, as far as it can be:

• a missing x or y is 0; a missing width is 250 and a missing height is 60; a size below 1 is raised to 1,
• a position or size given as a fractional number is rounded to an integer,
• a missing text, file or url is the empty string,
• a canvasColor given as a JSON number, e.g. 1, is read as the preset of that number, and the three-digit hex form "#f0a" is accepted,
• an attribute whose JSON type is not the one this spec asks for — including a canvasColor that is neither a preset nor a hex string — is left untouched as unrecognised data, and the attribute counts as absent,
• an edge naming a fromNode or toNode that no node has is kept; the canvas reports how many there are and offers to remove them.

Writing (addition)

• nodes and edges are always written, as arrays, even when empty.
• Attributes are written in the order this spec lists them, so a save produces a small diff rather than a reshuffle.
• Optional attributes that were absent stay absent.
• Hex colors are written in lowercase.
• The file is pretty-printed with two-space indentation and ends with a newline.