# 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](1.0.md) 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](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.