Inaccurate URL diagrams

[mszulcz-mitre]

Suspected issues

Some of the generated UML diagrams appear to be incorrect. For example, the diagram from Tutorial: Part 2 shows aggregation:

but in the diagram generated using gen-yuml -d . -f png personinfo.yaml (this command is suggested in Tutorial: Part 2), the terminal black diamonds on the aggregation arrows are missing:

Other diagrams appear to show duplicated arrows. For example, the figure made using gen-yuml slot-usage-example.yaml in Tutorial: Part 7 shows many arrows occurring in pairs:

Are these duplicated arrows supposed to be present?

To reproduce

aggregation

1. Go to Tutorial: Part 2.
2. Follow instructions to generate a yUML diagram gen-yuml -d . -f png personinfo.yaml.
3. Compare the generated diagram with the diagram in the tutorial.

duplicated arrows

1. Go to Tutorial: Part 7.
2. Review the last figure.

Expected behavior

I expected diamonds to appear in the UML diagram representing aggregation and I expected single arrows between objects.

[cmungall]

This is odd

Currently most people are using one of

• https://linkml.io/linkml/generators/plantumlgen.html
• or mermaid class diagrams, as part of https://linkml.io/linkml/generators/markdown.html

(or ER diagrams)

These are best supported. I think our best course of action is to deprecate yuml and update the tutorial. (but if anyone wants to make a PR for the yuml one that would be great)

There is some discussion here

• 1509

In my experience each tool has it's own oddities. Ideally we would decompose this into two steps: mapping LinkML to a UML serialization (not diagramming format), e.g XMI, and then use standard tools to go from XMI to various diagrams. But that doesn't seem to sit well with the way most non-commercial UML tooling seems to work these days...

[mszulcz-mitre]

Thank you for your quick response! I tried your suggestions but didn't have any luck.

Currently most people are using one of https://linkml.io/linkml/generators/plantumlgen.html or mermaid class diagrams, as part of https://linkml.io/linkml/generators/markdown.html

The mermaid class diagrams in generated markdown files (using gen-doc, which is recommended in the markdown page) also don't capture aggregation. Here's the mermaid diagram generated for the schema in Turtorial: Part 2.

The arrow doesn't have a terminal diamond showing aggregation. However, in the figure from Tutorial: Part 2 (which says, "CREATED WITH YUML"), the terminal diamond is present:

The mermaid diagram generated for personinfo-with-inheritance.yaml from Tutorial: Part 7 (again using gen-doc) also doesn't show aggregation:

The large diagram from the original post (the one with the duplicated arrows), however, does show aggregation:

Other issues

1. The mermaid diagram I generated for personinfo-with-inheritance.yaml above (the one with 3 purple boxes) is not the full system diagram (the biggest one shown above taken from Tutorial: Part 7). I'd love to include the full system mermaid diagram, but I can't seem to generate it in markdown. geo-doc --help shows a flag called --include-top-level-diagram that's supposed to Include ER diagram of the entire schema on index page, but it doesn't seem to work. Invoking it with mermaid class diagrams (the default) throws an error: AttributeError: 'NoneType' object has no attribute 'value'. Changing the digram type to er_diagram causes the error to disappear, but the diagram of the entire schema is still not included.
   • I'd like to be able to generate markdown files with a full system, accurate UML diagram that shows attributes--like the big one shown above, but without the duplicate arrows. Is there a way to do that?
2. In addition to not showing aggregation, the mermaid diagrams don't show class attributes like the YUML diagrams. Is there a way to make them?

[sujaypatil96]

Hi @mszulcz-mitre, thanks for your issue and trying out the suggestions from @cmungall!

The mermaid class diagrams in generated markdown files (using gen-doc, which is recommended in the markdown page) also don't capture aggregation. Here's the mermaid diagram generated for the schema in Turtorial: Part 2.

You're right, the Mermaid class diagram generator does not create aggregation (or composition) UML relationships. The only relationships that it does represent are dependency and generalization UML mermaid relationships. In the mermaid docs for making class diagrams: https://mermaid.js.org/syntax/classDiagram.html#defining-relationship these are the dependency and inheritance relationship types/arrows respectively.

The mermaid class diagrams which you are generating using gen-doc is definitely the recommended/up-to-date/better maintained way of generating UML class diagrams, but unfortunately it does not have full feature parity with the yUML diagram generator just yet. We've captured some of the missing features/details in #931 but haven't gotten the time to work on these as high priority items just yet. That being said, I think it's time to make them a high priority and work on them.

The mermaid diagram I generated for personinfo-with-inheritance.yaml above (the one with 3 purple boxes) is not the full system diagram (the biggest one shown above taken from Tutorial: Part 7). I'd love to include the full system mermaid diagram, but I can't seem to generate it in markdown. geo-doc --help shows a flag called --include-top-level-diagram that's supposed to Include ER diagram of the entire schema on index page, but it doesn't seem to work

Again, you're right. The gen-doc CLI tool currently only has the ability to generate class diagrams on a per class basis, i.e., one class diagram per class, and not a full/monolithic class diagram capturing relationships between all the classes in your model. Like you identified, the ER diagram is the only full system/model mermaid diagram that you can create.

We did a review of all the diagram generation tools in the linkml arsenal currently, and have been trying to prioritize the work to be done next. Here are the slides we used to drive a recent discussion on this topic: https://docs.google.com/presentation/d/1NEQX39Q3qemUO6h46Gy9Peiyf8vewx_9g-OfCUQe0fU/edit#slide=id.p

Outside of gen-doc you can also invoke the ER diagram generator as a standalone command line tool: https://linkml.io/linkml/generators/erdiagram.html using gen-erdiagram like this.

gen-erdiagram ~/path/to/personinfo-with-inheritance.yaml

Save the LinkML schema from https://linkml.io/linkml/intro/tutorial07.html#inheritance in a YAML file called personinfo-with-inheritance.yaml and run the above command.

You will see a Mermaid ER diagram like below.

erDiagram
Container {

}
Organization {
    string mission_statement  
    stringList aliases  
    string id  
    string full_name  
}
Person {
    string phone  
    integer age  
    stringList aliases  
    string id  
    string full_name  
}

Container ||--}o Person : "persons"
Container ||--}o Organization : "organizations"

Does this answer your question temporarily? I will look into why you are seeing that error.

In addition to not showing aggregation, the mermaid diagrams don't show class attributes like the YUML diagrams. Is there a way to make them?

Yes, you can customize the jinja template that controls/defines the way in which the Mermaid class diagrams are created here: https://github.com/linkml/linkml/blob/main/linkml/generators/docgen/class_diagram.md.jinja2. You can create your own custom jinja file called class_diagram.md.jinja2 anywhere in your repository, and allow gen-doc to make Mermaid class diagrams based on your class_diagram.md.jinja2 by pointing to the folder with this jinja using the --template-directory option.

[VladimirAlexiev]

@nlharris @sujaypatil96 @cmungall @mszulcz-mitre @Silvanoc @dalito

The yuml duplicated arrows are seen in the tutorial PersonInfo schema: https://github.com/linkml/linkml/blob/main/examples/PersonSchema/personinfo.png

I also vote to deprecate yuml and replace the tutorial diagrams with Mermaid or PlantUML. I think this is an important documentation issue that can confuse novice users, so I voted with 👍 on top (below the issue description). Please do the same, so it appears in the prioritized list!