Skip to content
Source on GitHubVisitors

Appendix D — Design rationale and open questions

Contents of DISL 0.1

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 not recurse, 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 for 0.2

  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.
  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.
  8. Constraint explanations: machine-generated explanations of why a CEL rule failed (counterexample elements), beyond the declared target.

Referenced from