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 December 27, 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 tab (desktop only):
Doing so will open a new panel 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 |
| backgroundColor | The background color of the resource. Can be any X11 color name or hex (e.g. #FF00FF). Defaults to white | 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). 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 |
| layout | A layout | object | 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 |
| type | The type of the perspective. Accepted values are flow and ring. Defaults to flow | string | false |
| extends | The previously-defined perspective that this perspective extends | string | false |
| relations | An array of relations | array | false |
| aliases | An array of aliases | array | false |
| overrides | An array of overrides | array | false |
| walkthrough | An array of slides | 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. | string | false |
| orientation | Which direction the perspective flows in. Accepted values are leftToRight and topToBottom. Defaults to leftToRight. | string | false |
| additionalContext | What additional context, if any, to show in this perspective. Accepted values are all, none, super-only and sub-only. Defaults to all. | 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. | 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. Not currently implemented | string | false |
| description | Specify to assign a different description to this resource. Not currently implemented | string | false |
| style | Specify to assign a different style to this resource. Not currently implemented | string | false |
| layout | Specify to assign a different layout to this resource. Not currently implemented | object | false |
Slide
Slides together form the walkthrough for a perspective.
| property | description | type | required |
|---|---|---|---|
| text | The text accompanying the slide. If not present, the previous slide’s text is used | string | false |
| select | The resource identifier (or comma-separated identifiers) to select. Selected resource(s) are displayed more prominently, and unrelated resource are hidden. If not present, the previous slide’s select value is used | string | false |
| expand | The resource identifier to expand (make full-screen). If not present, the previous slide’s expand value is used | string | false |
| highlight | The resource identifier (or comma-separated identifiers) to highlight. Highlighted resource(s) have an animated border, and unrelated resource are faded out | string | false |
Layout
These parameters govern how child elements are laid out inside of a parent.
| property | description | type | required |
|---|---|---|---|
| compactness | A number from 0.1 to 1 indicating how compactly child resources are rendered. Affects only context resources with more than one child. Defaults to 1 | number | false |
| sizes | If set to proportional, child sizes are proportional to the number of resources they are related to. If set to uniform, all children have the same size. Defaults to proportional. | string | false |