166 lines
6.3 KiB
Markdown
166 lines
6.3 KiB
Markdown
# Canvas Spec
|
|
|
|
<small>Based on JSON Canvas 1.0 — 2024-03-11</small>
|
|
|
|
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.
|