Skip to content
Source on GitHubVisitors

Appendix D — Design rationale and open questions

Contents of DISL 0.4

D.1 Rationale (informative)

Why JSON rather than YAML as the normative form? JSON has a single, unambiguous data model, universal parser support, and first-class JSON Schema tooling. It also avoids YAML's implicit typing pitfalls. Tool engineers who prefer YAML can write it and convert, because the logical content is identical, and persistence may still write DID definitions as YAML (11.2).

Why CEL? DISL needs expressions everywhere, but it must stay safe to load specifications from untrusted sources and must guarantee termination for live evaluation on every keystroke. CEL is non-Turing-complete, side-effect free, has a static type checker and cost estimation, and runs in all major ecosystems. User functions are allowed, but may recurse only into themselves and only to a declared depth (3.4), which preserves those guarantees. OCL was considered too heavy, and JavaScript too powerful.

Why coordinate systems as a separate layer? Coordinates carry meaning in many diagram kinds (schedules, lanes, sequences, floor plans), and snapping only makes sense in domain units ("snap to working days"). Binding coordinates to attributes removes the classic duplication between a task's date field and its position on the canvas, along with the bugs that duplication causes.

Why per-axis snapping? Real diagrams often need different discreteness on each axis: continuous time with discrete lanes, discrete time with free vertical stacking, a coarse horizontal grid with a fine vertical one. A single "grid size" cannot express that.

Why flat element lists in DID definitions? Nesting elements physically makes moves between containers produce large diffs and makes merge conflicts likely. Flat lists with parent references keep changes local.

Why so much documentation structure? A diagram type is also a teaching tool. When every type, field, rule and snapping behavior can explain itself, users learn the language while working, and documentation cannot drift from the implementation because both come from the same source.

D.2 Open questions

The questions 0.1 left open, and what 0.2 did with them. Items marked answered or partly answered say where.

  1. Diagram-to-diagram links: references across DID definitions (a sub-process defined in another file) and their persistence and integrity rules.
  2. Typed CEL for view-only data: stronger static typing for self.view fields per coordinate system (currently dyn).
  3. Animation and simulation: a standard extension profile for token-flow animation (Petri nets, BPMN simulation) driven by CEL. Answered in 0.2 by simulated runs (9.6): stepwise states computed in CEL, played outside the model's history; a token-flow profile can be written with them.
  4. Responsive notation: notation variants driven by available screen size (mobile editing).
  5. Standard library packaging: a registry of shareable DISL libraries (shapes, markers, themes) with semantic versioning and signatures.
  6. Bidirectional text formats: declaring a textual syntax (grammar) alongside the graphical one, to support round-tripping with textual DSLs such as PlantUML or Mermaid.
  7. Accessibility conformance: measurable requirements (contrast ratios of built-in tokens, keyboard coverage) as a conformance class of its own. Partly answered in 0.2: a specification can state and have validated the contrast of its own tokens (6.2); a conformance class is still open.
  8. Constraint explanations: machine-generated explanations of why a CEL rule failed (counterexample elements), beyond the declared target. Partly answered in 0.2: one finding per failing item with forEach (8.2), cycles named in loop order (12.4), detail in built-in messages and violation in built-in refusals (8.1), and reasons for every refusal (2.3); machine-generated counterexamples are still open.
  9. Layouts: declaring layout algorithms themselves (layered, banded, row-packed, compact, radial) rather than naming them for a plugin to supply (section 10), so that every host arranges a diagram the same way. The next open question after 0.2. Partly answered in 0.3 and 0.4: three standard algorithms (10.1 to 10.3), and the properties a tiered force layout's result must have (10.4); a fully defined force layout is still open.

Referenced from