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.
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 firstname.lastname@example.org or @ilographs on twitter.
|resources||An array of resources (the resource tree)||array||false|
|perspectives||An array of perspectives||array||false|
Resources are the building blocks of ilograph diagrams. Resources can appear in multiple perspectives.
|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:
|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|
Each perspective in an ilograph diagram gives a unique view of the relations between the diagram’s resources.
|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:
|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|
Perspective relations define how resources are related to each other in a perspective.
|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|
Perspective aliases is an advanced tool used to redefine resource ids in a perspective.
|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|
Perspective overrides are used to override parents, subtitles and descriptions of resources in a perspective.
|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|