Support for annotation-based diagram filtering

[NicolasRouquette]

User Story

As an OML author, I would like to be able to specify the subset of an ontology that should be visualized on a diagram using annotations that are placed on elements in that subset.

Detailed Description.

Consider this vocabulary:
https://github.com/opencaesar/vocabularies/blob/vocabularies%231/src/main/oml/opencaesar.io/foundation/metrology.oml

Diagramming the whole metrology vocabulary is a nice capability but the resulting diagram is difficult to use because related entities can be far apart from each other in the diagram layout.

Instead of trying to come up with smarter diagram layout engines, it is often easy to get domain-specific hints about what constitutes a useful domain-specific diagram views. The collection of such views then can cover the scope of a complex vocabulary while each view is more limited in scope so that a reasonable diagram layout engine can produce a usable rendering of that limited scope.

In the case of metrology, domain-specific views could corresponds to the SysML QUDV diagrams, that is:

• A "core" diagram showing only:

  • Unit & SystemOfUnits
  • QuantityKind & SystemOfQuantities

• A "unit" diagram showing all the variants of Unit

• A "quantities" diagram showing all the variants of QuantityKind

• There could be a 4th diagram not shown in the SysML specifications about dimensions
  That is, dimensions make sense in the context of a SystemOfQuantities for which some QuantityKinds are chosen as "bases" and all other QuantityKinds are, for that system, effectively derived.

To avoid cluttering the OML content with diagram-related annotations, it would be nice to segregate the OML content, say, in src/oml from the diagrams, say, in src/diagram, where the latter has oml ontologies with diagram annotations in .omldiagram files.

An OML ontology file could have one or more OML diagram files extending it with diagram annotations.

• The contents of the diagram would be specified via a vocabulary of built-in OML diagram annotation properties for specifying diagram-related presentation aspects, including but not necessarily limited to the following:

  • diagram ontology IRI can be used to establish a hierarchical namespace for the diagram
  • Annotations dc:title & dc:description on the OML ontology itself can be interpreted as the diagram title and description.
  • Annotation diagram:include and diagram:exclude on OML elements to enable/disable visualizing them in the diagram.
  • Annotation diagram:include and diagram:exclude on the ontology element representing global filters to apply to elements of certain kinds.
  • Annotations on elements to customize the details of their notation
  • Annotations to include elements related to the explicitly included elements by some relation to some depth.

Note that the scope of elements that may be visualized in a given diagram include elements defined in ontologies in its import closure (i.e., all transitively imported ontologies).

Acceptance Criteria

• A http://opencaesar.io/oml/diagram vocabulary that defines annotations for controlling diagram visualization. The vocabulary provides a set of basic annotation properties, and documents what elements they can be placed on, and the semantics of placing them on those elements. The vocabulary will be part of the https://github.com/opencaesar/vocabularies repository.
• A set of .omldiagram file that visualize the set of vocabularies in https://github.com/opencaesar/vocabularies. These files should be in a different folder (e.g., src/diagram) from the vocabularies (e.g., in src/oml).
• A prototype of rendering .omldiagram files in the OML Theia in a way that respects the annotations.

Note that this ticket is focused on exploring this design and prototyping. It is not the ultimate implementation ticket.
Note: one source of good notational option for a class diagram that we can consider is here.