IDL Part 2: The IDL Specification

This is part 2 of a series of posts on the ilograph diagramming language (IDL). If you haven’t already, please see the introduction to the IDL in part 1. This post contains the current specification for the IDL; in part 3, we’ll look at some more advanced features.

Note: this spec was last updated on June 22, 2019.

While this is a good reference, getting acquainted with the IDL is probably best done by viewing an IDL example. To do so, visit one of the sample ilographs and click this icon (desktop only):

Doing so will open a new window with the source of the ilograph (written in IDL). You can reference it while browsing the ilograph diagram in the main window:

Without further ado, here is the IDL spec. If you have any questions or suggestions, please reach out to me at billy@ilograph.com or @ilographs on twitter.

Top-level properties

property description type required
resources An array of resources (the resource tree) array false
perspectives An array of perspectives array false

Resource

Resources are the building blocks of ilograph diagrams. Resources can appear in multiple perspectives.

property description type required
name The name of the resource. Used as the identifer of the resource if id is not provided. If name contains a restricted character (/, ^, * or ,), id must be defined. string true
subtitle The subtitle of the resource (appears below the resource name) string false
description The description of the resource (appears below the resource subtitle when focused). Has limited support for markdown elements: **bold**, *italics*, and [links](https://www.ilograph.com) string false
color The text color of the resource. Can be any X11 color name or hex (e.g. #FF00FF). Defaults to dimgray string false
style When set to plural, the resource is rendered as multiple boxes. When set to dashed, the resource border is rendered as a dashed line. Accepted values are default, plural, and dashed. Defaults to default string false
abstract When set to true, other resources may inherit from this resource using instanceOf (see below). Only top-level resources may be declared abstract. Abstract resources cannot be referenced directly in perspectives boolean false
instanceOf When specified, this resource inherits all properties (other than id/name) and child resources of the specified abstract resource. Any additional properties specified, including children, will override the inherited property value string false
children An array of child resources array false
id An substitute identifier for the resource. Cannot contain /, ^, * or , characters string false

Perspective

Each perspective in an ilograph diagram gives a unique view of the relations between the diagram’s resources.

property description type required
id A unique identifier for the perspective. If not provided, the name property is used as the perspective identifer string false
name The name of the perspective. Used as the unique identifer of the perspective if id is not provided string true
notes Notes that appear in the notes panel when viewing the perspective. Should be used to describe the perspective. Has limited support for markdown elements: **bold**, *italics*, and [links](https://www.ilograph.com) string false
color The color of the perspective. Can be any X11 color name or hex (e.g. “#FF00FF”). Defaults to royalblue string false
relations An array of relations array false
aliases An array of aliases array false
overrides An array of overrides array false
defaultRelationLabel The default label for relations that don’t have a label specified string false
arrowDirection The default arrow direction for relations. The direction specified is relative to the perspective’s orientation. Individual relations can override this value by specifying their own relation value. Accepted values are forward, backward, and bidirectional. Defaults to forward. bidirectional is not currently supported string false
orientation Which direction the perspective flows in. Accepted values are leftToRight, rightToLeft, topToBottom, and bottomToTop. Defaults to leftToRight. Only leftToRight is currently supported string false
hidden If true, the perspective is not shown in the perspective list boolean false

Relation

Perspective relations define how resources are related to each other in a perspective.

property description type required
from The identifier (or comma-separated identifiers) of the dependent (left-side) resource(s) in this relation. Can refer to resource ids, alias ids, or compound identifiers string true
to The identifier (or comma-separated identifiers) of the independent (right-side) resource(s) in this relation. Can refer to resource ids, alias ids, or compound identifiers string true
label The label that appears above the arrow in this relation string false
description The extended description that appears when the user’s mouse hovers over the arrow in this relation string false
arrowDirection The arrow direction for this relation. The direction specified is relative to the perspective’s orientation. Accepted values are forward, backward, and bidirectional. Defaults to forward. bidirectional is not currently supported string false

Alias

Perspective aliases is an advanced tool used to redefine resource ids in a perspective.

property description type required
alias The identifier for this alias. Can be used to override an existing resource id. Cannot contain /, ^, * or , characters string true
for The value of this alias. Typically is a compound identifier string true

Override

Perspective overrides are used to override parents, subtitles and descriptions of resources in a perspective.

property description type required
resourceId The resource identifier (or comma-separated identifiers) to override string true
parentId Specify to assign a different parent to this resource string false
subtitle Specify to assign a different subtitle to this resource string false
description Specify to assign a different description to this resource string false
style Specify to assign a different style to this resource string false