Concise json graph format

[uruuru]

In #27 @tylerlong suggested to create a more concise version of ELK's json format, which is transformed into the classic json format. Comments are welcome, I'll update this description until a final decision is made.

In my oppinion in should be consistent to ELK's text format where possible.

Features shall include:

• Optional ids. They shall be generated automatically if omitted. I feel, however, that the generation should be as deterministic as possible.
• Inheritence of layout options.
• More concise syntax for edges and labels.
• Allow to specify a (global) default for element dimensions.

Labels

{ id: "n1", label: "foo" } and { id: "n1", labels: { "foo" } }
translate to { id: "n1", labels: [ { id: "l1", text: "foo" } ]

Edges

Syntax consistent with ELK text:
edges: [ "n1->n2", "n2->n3" ]
translates to edges: [ { id: "e1", sources: ["n1"], targets: ["n2"] }, { id: "e2", sources: ["n2"], targets: ["n3"] }]

Mixing objects and strings:
edges: [ 'n1->n2', { sources: ["n2"], targets: ["n3"] } ]

[tylerlong]

One concern is: ELK is just layout engine, it doesn't care about rendering. But as an end user I do care.

For example, when I try to render an edge, I might want to choose to render it as undirected/arrowed/dual-arrowed edge. I might even want to draw a marker in the middle of an edge.

Ref: http://tutorials.jenkov.com/svg/marker-element.html

So the edge expression I used is

• n1 ==> n2, It means there is an arrow in the end of the edge.
• n1 == n2 means there is no arrow.
• n1 <==> n2 mean there are arrows in both ends.
• An even complicated exaple: n1 <=o=> n2, there is an o marker in the middle. (svg code: marker-mid="url(#o)")

What I said above is mostly above rendering detail instead of layout. So I am still thinking whether it should be added in this project.

I use ==> instead of --> because -is common character in id, which makes parsing hard.

I use == instead of =, because I want to support marker-mid.

[tylerlong]

I have experience with React/JSX, and I am thinking maybe the following syntax is even better:

<node>
  <node id="n1"/>
  <node id="n2"/>
  <edge expr="n1 ==> n2"/>
</node>

I think it is even more readable & concise than the proposed concise JSON format:

{
  children: [
    {
      id: "n1"
    },
    {
      id: "n2"
    }
  ],
  edges: [
    {
      expr: "n1 ==> n2"
    }
  ]
}

[uruuru]

ELK is just layout engine, it doesn't care about rendering. But as an end user I do care.

As you say, it doesn't (and won't) care about rendering. There are just too many requirements and desires to capture them in one format. That's already true for the edge formats you list.
However, since it's json, you can add whatever information to each element and interpret them in whatever way you want. It seems a bit inefficient to send all those extra information to the layout engine though.

I think it is even more readable & concise than the proposed concise JSON format:

For one thing, I'm not sure whether people would really prefer xml. For another thing, there's no advantage from the library's point of view to use a format different from json.

If you want to move away from json and have a really concise DSL: there's already the ELK text format.

[tylerlong]

I have a question: Is there a JS method to convert between ELK JSON format and ELK text format? Or does elkjs support ELK text format directly so that I don't need to convert it to ELK JSON format first?

I think there are two formats which are well-understood by frontend developers (visual graphs are mainly about frontend in my opinion): JSON and HTML. So I think both of them will be easily adopted. I propose the HTML style format because it's used by JSX to build UI and lots of people seem to like it. I don't have a clear goal yet, the general rule is to create a format easy to read, write and adopted.

I am writing a project based on elkjs. It has the rendering part. If I want users to use it (or at least myself feel pleasant to use it), I have to replace the ELK JSON format. I will think whether I will go with the ELK text format.

[uruuru]

The ELK text format is implemented in Xtext (which is implemented in Java) and not directly understood by elkjs. I'm not aware of any pure JS method to work with xtext languages. Maybe @spoenemann can comment on this.

[spoenemann]

Xtext always requires a Java backend.

[uruuru]

I won't have the time to work on this, hence I'm closing the issue. I've seen a different project that has a more concise format which translates into elk json (but forgot the name .).