Diagram Types

[aschrijver]

The current spec v1.0 defines "nodes + edges on a canvas" and some general metadata on nodes and edges. Very minimal, which is good.

In terms of minimalism as well as the need to convert a diagram into specific export formats it would be fantastic to see support for definition of Diagram Type. Examples of types:

• UML Class Diagram
• Mindmap Diagram
• Sticky Notes (brainstorming / ideation)

And an example of more domain-specific diagram types:

• Event Storming Diagram (specialisation of sticky note diagram)
• Event Modeling Diagram (a complex diagram type)

What would the Diagram Type be used for:

• Load tool palettes exclusively containing relevant shapes and tools.
• Indicate diagram validity or restriction of illegal actions ("can't connect these shapes").
• Allow export to valid domain-specific data format / controlled vocabulary.
  • E.g. in case of the event diagrams the export might be used to bootstrap Event Catalog and generate boilerplate code for your eventsourcing project.

Thus far I haven't found universal way to define diagram types in any canvas-based diagramming solution. Restricting the UI to conform to a specific diagram type involves custom API's and even then cannot be fully achieved (unless by signficant custom code and/or forking the diagrammer codebase).

In most canvas-based diagrammers you draw rather than diagram. I.e. a adding a sticky note involves creating a rectangle, giving a color, sometimes adding a textbox within and grouping that with the rectangle. That makes it hard, highly customised, or unfeasible to export to a specific format / vocabulary.

[nichtich]

Specific definition of diagram types looks like out of the scope of a minimal specification but we could provide methods for others to define such types. I'd suggest to extend the data model with a generic properties field holding arbitrary key-value pairs like usual in Labeled Property Graphs.

[aschrijver]

Question is what is a minimum specification of a diagram type that adds sufficient value to be usable?

An extension mechanism as you describe would come some way of letting external parties bring additional functionality by adding extra metadata to a node or an edge. An addition should be to allow adding metadata on the diagram itself.

If the main objective of the diagram type is to allow it to be exported to some domain-specific format, so it can be directly ingested by some automated system, then the spec need not define all the diagramming logic and can defer some of that to the diagrammer implementation.

(Below quite incomplete, just sketch the idea.)

{
  "definition": {
    "label": "Event Storming Diagram",
    "shapes": [
      {
        "name": "Command",
        "type": "text",
        "color": 5
      },
      {
        "name": "Event",
        "type": "text",
        "color": 2
      },
      {
        "name": "Actor",
        "type": "text",
        "color": 3
      }
    ]
  },
  "nodes": [
  ],
  "edges": [
  ]
}

PS. Wrt an extension model in general, beware that a properties field leads to backwards-compatibility issues if ever a property gets 'promoted' to be part of the standard itself. Here the problem of JSON extensions is explained for the CloudEvents spec.

PS2. The spec should probably have a version property, or declare that any change MUST be backwards-compatible.