The Ilograph Spec
Note: this spec was last updated on August 13, 2024.
| property | description | type | required |
|---|---|---|---|
| resources | An array of resources (the resource tree) | array | no |
| perspectives | An array of perspectives | array | no |
| imports | An array of imports | array | no |
| contexts | An array of contexts | array | no |
| description | A description of the diagram that appears at the top of the overview page. Has support for markdown, and can contain multiple lines. | string | no |
| defaultContextDisplayName | The display name of the default context | string | no |
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 | yes |
| subtitle | The subtitle of the resource (appears below the resource name) | string | no |
| description | The description of the resource (appears below the resource subtitle when focused). Has support for markdown. Descriptions can contain multiple lines or be defined as key-value pairs. | string|object | no |
| color | The text color of the resource. Can be any X11 color name or hex (e.g. #FF00FF). Defaults to dimgray. This color is inverted when dark mode is enabled by the user | string | no |
| backgroundColor | The background color of the resource. Can be any X11 color name or hex (e.g. #FF00FF). Defaults to white. This color is inverted when dark mode is enabled by the user | string | no |
| style | The resource border 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. When set to outline, the resource border is rendered as a solid line. When set to flat, no border is rendered. Accepted values are default, plural, dashed, outline, and flat. Defaults to default | string | no |
| 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 | no |
| 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 | no |
| children | An array of child resources | array | no |
| icon | An icon path | string | no |
| iconStyle | Controls how the icon is rendered. If set to default the icon is rendered normally. If set to silhouette, the icon is rendered as an outline in the same color as the resource text. Defaults to default | string | no |
| url | A URL for the resource. If defined, a “link” icon linking to the URL appears in the resource when it is selected | string | no |
| layout | A layout | object | no |
| id | An substitute identifier for the resource. Cannot contain /, ^, *, [, ], or , characters | string | no |
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 | no |
| name | The name of the perspective. Used as the unique identifer of the perspective if id is not provided | string | yes |
| notes | Notes that appear in the notes panel when viewing the perspective, and in the overview page. Should be used to describe the perspective. Has support for markdown, and can contain multiple lines. | string | no |
| color | The color of the perspective. Can be any X11 color name or hex (e.g. “#FF00FF”). Defaults to royalblue | string | no |
| extends | The previously-defined perspective (or comma-separated perspectives) that this perspective extends. When specifying multiple perspectives to extend, they are applied in the order they are specified. Values from perspectives listed later take precedence. | string | no |
| relations | An array of relations | array | no |
| sequence | A sequence object | object | no |
| aliases | An array of aliases | array | no |
| overrides | An array of overrides | array | no |
| walkthrough | An array of slides | array | no |
| defaultArrowLabel | The default label for relation/step arrows that don’t have a label specified | string | no |
| defaultArrowColor | The default color for relation/step arrows that don’t have a color specified | string | no |
| 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. Does not affect sequence perspectives | string | no |
| orientation | Which direction the perspective is oriented. Accepted values are leftToRight, topToBottom, and ring. Defaults to leftToRight. Does not affect sequence perspectives | string | no |
| additionalContext | What additional context, if any, to show in this perspective. Accepted values are all, none, super-only and sub-only. Defaults to super-only. Read more about controlling context. | string | no |
| unwrapContext | If true, context resources may be ommited to ensure that relation arrows always flow in the specified arrowDirection. If false, resources always appear in their parent context resource, and arrow directions will automatically reverse to accomodate this. Defaults to false. Does not affect sequence or ring perspectives | boolean | no |
| deduplicateImportedResources | If true, resources that are imported multiple times will be de-duplicated in this perspective. If false, every imported instance of a resource will appear as a unique resource. Defaults to true. | boolean | no |
| hidden | If true, the perspective is not shown in the perspective list | boolean | no |
Relations define how resources are related to each other in the perspective. Perspectives with relations are relation perspectives. Each relation must define from or to.
| 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 or alias ids | string | no |
| to | The identifier (or comma-separated identifiers) of the independent (right-side) resource(s) in this relation. Can refer to resource ids or alias ids | string | no |
| label | The label that appears above the arrow(s) in this relation | string | no |
| description | The extended description that appears when the user’s mouse hovers over the arrow(s) in this relation. Has support for markdown, and can contain multiple lines. | string | no |
| 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 | no |
| color | The arrow and text color of the relation. Can be any X11 color name or hex (e.g. #FF00FF). Defaults to #303030. This color is inverted when dark mode is enabled by the user | string | no |
| secondary | If true, the relation will not affect the perspective’s layout. Does not affect ring perspectives. Defaults to false. | boolean | no |
When sequence is set in a perspective, the sequence defines how resources are related in a sequence of steps in the perspective. Perspectives with sequence defined are sequence perspectives.
| property | description | type | required |
|---|---|---|---|
| start | The identifier of the starting resource in the sequence | string | yes |
| steps | An array of steps | array | no |
The steps in a sequence defines the steps between resources in the sequence and their labels. Each step must define to, toAndBack, toAsync, or restartAt.
| property | description | type | required |
|---|---|---|---|
| to | The identifier of the resource this step of the sequence is to | string | no |
| toAndBack | The identifier of the resource this step of the sequence is to. A second step back to the previous resource is automatically added | string | no |
| toAsync | The identifier of the resource this step of the sequence is to. Unlike with to, however, control is not passed to the new step. Async steps are drawn with dashed arrows | string | no |
| restartAt | The identifier of the resource to pass control to without drawing an arrow. The next step will originate from this resource | string | no |
| label | The label that appears above the arrow of this step | string | no |
| description | The extended description that appears when the user’s mouse hovers over the arrow of this step. Has support for markdown, and can contain multiple lines. | string | no |
| bidirectional | If true, arrow(s) for this step are show with arrowheads on both ends. Defaults to false. | boolean | no |
| color | The arrow and text color of the step. Can be any X11 color name or hex (e.g. #FF00FF). Defaults to #303030. This color is inverted when dark mode is enabled by the user | string | no |
Perspective aliases are used to give a convenient names to resource reference(s). Read more about aliases.
| property | description | type | required |
|---|---|---|---|
| alias | The identifier for this alias. Can be used to override an existing resource id. Cannot contain /, ^, *, [, ], or , characters | string | yes |
| for | The value of this alias. Typically is a comma-seperated list of identifiers | string | yes |
Perspective overrides are used to override parent of resources in a perspective. This is handy for showing resources in different contexts.
| property | description | type | required |
|---|---|---|---|
| resourceId | The resource identifier (or comma-separated identifiers) to override | string | yes |
| parentId | Specify to assign a different parent to this resource for the perspective, or none to assign no parent | string | no |
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. Has support for markdown, and can contain multiple lines. | string | no |
| 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. Use ^ to not select any resource. | string | no |
| expand | The resource identifier to expand (make full-screen). If not present, the previous slide’s expand value is used. Use ^ to not expand any resource. | string | no |
| highlight | The resource identifier (or comma-separated identifiers) to highlight. Highlighted resource(s) have an animated border, and unrelated resource are faded out | string | no |
| detail | The level of detail used during the slide. Can be between 0.001 (very low detail) and 1 (full detail). Defaults to 1 if not present | number | no |
Each context defines a context for a diagram.
| property | description | type | required |
|---|---|---|---|
| name | The name of the context. Must be unique and cannot be “Default” | string | yes |
| roots | An array of Context Entries | array | no |
| extends | The previously-defined context (or comma-separated contexts) that this context extends | string | no |
| hidden | If true, the context is not shown in the context dropdown | boolean | no |
Context entrys form a tree-like structure for defining a context.
| property | description | type | required |
|---|---|---|---|
| resourceId | The identifier (or comma-separated identifiers) for this entry | string | yes |
| children | An array of child context entries. Cannot be defined if more than one resource is specified in resourceId | array | no |
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 | no |
| sizes | If set to proportional, child resource sizes are always proportional to the number of resources they are related to. If set to uniform, all children always have the same size. If set to auto, the layout engine automatically chooses on a per-perspective basis. Defaults to auto | string | no |
Imports define a list of diagrams to import and their namespaces. See imports for more information.
| property | description | type | required |
|---|---|---|---|
| from | The diagram to import | string | yes |
| namespace | Namespace prefix for imported resources and perspectives. Cannot contain restricted characters (/, ^, *, [, ], or ,) | string | yes |