Anatomy of a LionWeb Model

The id of a node is a string of arbitrary length, consisting of characters A-Z, a-z, 0-9, dash - and underscore _. It cannot be empty, and it must be unique for all nodes in the model.

The valid character set coincides with the output of base64url-encoding. This comes very handy if we had to derive the node id from some other source, like a binary hash, or a fully qualified name.

We chose this character set, as it should be compatible with any run-time environment, and avoid any encoding issues. We don’t limit the id’s length, so any kind of other source can be represented — fully qualified names tend to get very long, for example.

We assume nodes with equal id string to be identical.

Node ids should NOT carry any meaning: Only because a node id happens to contain the string frontLeftWheel, we should NOT assume its classifier might be Wheel, or its containment might be frontLeft. These "descriptive" node ids are quite useful to read examples or in tests, as they provide more context. However, examples and tests are for human consumption — real nodes (in their raw form) are not.

Before we get to the next part of a node, classifier, we need to discuss meta-pointers. Any time we refer from an instance model (M1) to its metamodel (M2 a.k.a. language), we use meta-pointers. They are a triple of {language key, language version, element key}, for example {language=MyLanguage, version=23-alpha, key=MyConcept}. Both language key and element key use the same character set as node ids, whereas language version can be any non-empty string.

We need this triple, because a language can be uniquely identified by its key and version, and the element key must be unique within its language. With language version we support language evolution, i.e. the fact that real-world languages tend to change over time.

We don’t prescribe anything about language version, as different implementations might use different ways to represent language evolution. We just assume that equal strings refer to the identical version.

A node’s classifier is a meta-pointer that defines the node’s nature, or type or class — "what kind of thing is this node?" A classifier of a node is equivalent to the class of a Java, C#, or TypeScript object. The classifier can either be a concrete concept or an annotation. It cannot be an abstract concept or interface, as we cannot instantiate them.

A node must conform to its classifier. This means the node can only have features as described in the node’s classifier. ^[1]

The parent of node A is the node B that contains A. For example, node 10 of classifier Car might contain node 5 of classifier PetrolEngine, and node 11 of classifier SteeringWheel. Thus, the parent of 5 is 10, and the parent of 11 is also 10.

Every node MUST have exactly one parent — except for root nodes. This implies that, starting from a root node, we can order all nodes in tree shape.

The opposite of a node’s parent are a node’s children. In the example above, node 10 has children 5 and 11; node 5 does not have any children.

A node’s classifier defines which kind of children a node can have — the node’s containments. In our example, node 5 might be contained in engine, and node 11 in steering — both defined in classifier Car.

Additionally, a node can have annotation instances. Let’s add a node 22 of annotation DiagramPosition to our 10:Car, and node 33 of annotation ReviewComment to 11:SteeringWheel. Thus, the parent of 22 is 10, and the parent of 33 is 11. We also call this the annotated node: node 10 has annotation 22, and node 22 has annotated node 10.

In summary, a node’s parent must always have a counterpart — either in the parent’s children, or in the parent’s annotation instances.

If we deleted the parent node, we implicitly deleted all its children and annotation instances, each of their children and annotation instances, and so on. In other words, a child or annotation instance shares the lifetime of its parent.

This also explains why we consider the annotated node the parent of an annotation instance: If the annotated node is gone, the annotation instance makes no sense anymore — they share the annotated node’s lifetime.

We use properties to store simple values inside a node. A node of classifier Person might have properties name: String, age: Integer and alive: Boolean.

A node’s classifier describes which properties can appear in the node. This description includes the property’s name, key, whether it is optional, and its type. On low-level serialization, we use a meta-pointer to refer to the description for each property value.

The property’s name is for humans to understand the property; we use the key to uniquely identify the property technically. With the optional flag we specify whether a node without this property is considered valid or not: In our system, a person without known name might be a problem, but we could still process them without knowing their age.

A property’s type describes what kind of values can appear in that property. All LionWeb data types, and thus all properties, are value types^[2]. This means they don’t have any identity, we just know their value: We can distinguish 10 and 15, but 12 and 12 are the same.

Some modeling frameworks allow properties with multiple values, e.g. luckyNumbers: Integer[0..*] = {23, 42, 4711}. LionWeb does not support that, because the values don’t have identity. So if we first had a property value of {23, 42}, and then {23, 42, 42}, we have no way of telling whether the new 42 has been inserted or appended. This leads to all kinds of problems we’d like to avoid.

The following subsections describe the kinds of data types supported by LionWeb.

A node A can contain other nodes B and C. Then B has the parent A; A has children B and C. If C contains D, then D has the ancestors C and A; A has the descendants B, C, and D.

Every node (except root nodes) must have exactly one parent, thus no node can be contained more than once. Containments establish a tree shape of the model (sometimes called primary containment tree or dominator tree). A node can never contain itself, neither directly nor indirectly.

We use containments if the contained node only makes sense together with its parent — a Coordinate is not very useful if we don’t know which shape it belongs to. We also identify different containments — for a Rectangle, we want to know whether a contained Coordinate is topLeft or lowerRight.

A node’s classifier describes the valid containments. This description includes the containment’s name, key, whether it is optional, whether we allow multiple nodes in the containment, and its type. On low-level serialization, we use a meta-pointer to refer to the description for each containment.

Name, key and optional flag mean the same for containments as for properties. Contrary to properties, a containment can be singular or multiple. A singular containment (i.e. multiple = false) allows only one contained node, e.g. a Rectangle can contain only one topLeft coordinate. In contrast, a House can contain multiple Rooms. For multiple containments, we keep track which child is contained at which position. As every contained node can have only one parent, we cannot have duplicates in multiple containments. Thus, multiple containments behave like an ordered set.

A containment’s type refers to a classifier, and describes which nodes can be part of that containment. Only nodes that have a compatible classifier can be part of that containment.

On serialization level, we store the contained node’s id for a containment. A containment is invalid if the contained node’s id cannot be resolved.

A node can point to other nodes it has some relation to. For example, a Project might refer to its mainResponsible: Employee, or to all its externalParties: BusinessPartner[0..*]. The node containing the reference is called source, the referred node is called target of the reference. A node can be referenced by none, one, or many other nodes. It can be referenced by itself. A node can reference another node (or itself) more than once. Thus, multiple references behave like a list.

A node’s classifier describes the valid references. This description includes the references’ name, key, whether it is optional, whether we allow multiple targets in the reference, and its type. On low-level serialization, we use a meta-pointer to refer to the description for each reference.

The description means the same as for containments, respectively. For multiple references, we keep track which target is listed at which position. The same target can appear several times in a multiple reference. This can help, for example, to describe steps: steps: Task[1..*] = {generate, saveAll, compile, saveAll} refers to Task saveAll twice.

LionWeb does not support bidirectional references. They are very hard to maintain, and also hard to process (i.e. if we want to traverse the whole model).

A contained node shares the lifetime of its parent — if the parent is deleted, the contained node gets deleted, too. The contained node makes no sense without its parent. Even if we kept the contained node, where would it go? We’d need to invent some special place for it. In contrast, the target of a reference is perfectly valid without the source. They can be deleted independently, and don’t need to be deleted when sources pointing to them are deleted.

Containments establish a tree shape for the model. With references, we regard the model as a graph, as a node can be target of several references.

For containments, the parent node only stores the child node’s id. For references, the source node stores the target node’s id and/or resolveInfo.

LionWeb does not support unresolvable containments, but unresolvable references are allowed.

Annotation instances are mostly regular nodes, with two exceptions: Their classifier must be an annotation, it cannot be a concept. Also, the annotation instance must be mentioned in its parent’s annotation instance list, it cannot be mentioned in the parent’s containments. Both these criteria are indirect; thus, when only looking at a node (without examining its classifier or parent), we cannot distinguish annotation instances from other nodes. That’s by design: everything is a node, remember?

An annotation instance can have any kind and amount of properties, containments, references, and other annotation instances. We can use annotation instances as reference target.

Assuming node X mentions node Y in X's annotation instances, we say X is annotated by Y, and Y has annotated node Y. Y's annotated node is always also Y's parent node.

Annotation instances share the lifetime of their annotated node; when we delete the annotated node, the annotation instance gets also deleted.

We keep track of the order of annotation instances. As every annotation instance can have only one parent, we cannot have duplicates in annotations. Thus, annotation instances behave like an ordered set.

Both a contained node C and an annotation instance A share the lifetime of their parent node P. So what’s the difference?

A containment must be described in the parent’s node classifier. If the parent is of classifier House with containments rooms, and doors, we (as users of that classifier) cannot add a containment windows to the parent node. The designer of classifier House made the choice that for their domain, a house should only care about rooms and doors, but not windows. The designer might not have anticipated our use case of their domain. But every user of that classifier relies on this structure of a house, so we must not mess with it.

An annotation instance cannot be mentioned in the parent’s node classifier at all. Instead, an annotation instance’s classifier must be an annotation, which mentions the classifier it annotates. Thus, the designer of the annotation decides which targets their annotation is applicable to. So we can come up with an annotation WindowAnnotation that annotates: House, and attach instances to nodes of classifier House. All these nodes still adhere to the intents of House's designer, but also transport the additional information about windows we need for our use case.

Even more importantly, we can put orthogonal concerns into annotation instances. For the domain of our functions with arguments, we don’t want to bother with the details how a parser constructed that node. But it would be useful to show users where this node originated from in case of errors. Not a problem with an annotation SourcePosition. Similarly, we could come up with an annotation ReviewComment that annotates: Node (i.e. any node), to be used during code reviews. The reviewer can attach instances to any node, without interfering with the original intent of these nodes.

Review comments demonstrate one drawback of annotations: we’re violating the generally valued idea of separating concerns, as we mix domain concerns and process concerns in the same model. The alternative would be to keep both concerns in separate models, and have the review comments reference the node they apply to. Experience shows this approach is very hard to maintain: What happens if we deleted a function, and there’s still a review comment referring to it? The review model might not be loaded during the deletion, so it now contains a "zombie" review comment. We might need to introduce "garbage collection" strategies to find such zombies and deal with them. For more context-sensitive annotations, moving the annotated node might introduce similar problems: The annotation instance might not make sense in the context of the annotated node’s new position. As example, imagine an annotation Profiling { cpuPercentage: Integer; annotates = Statement }. This annotation is not only meaningless, but actually wrong if the statement were moved somewhere else.

Annotations should not be used as replacement for proper concept design. If our language dealt with the domain of houses, review comments are completely independent of that domain, should not be part of it, and are perfect candidates for annotations. However, if our language was modeling discussions, then reviews and comments are integral part of that domain, and should be represented by proper containments and (abstract) concepts in our language. In this case, using annotations only because they seem conveniently applicable at lots of places is a strong modeling smell.

Classifiers define the nature / type / class of a node. LionWeb knows three kinds of classifiers: concepts, annotations, and interfaces. Every classifier can define an arbitrary number of features.

All classifiers support inheritance, meaning that a classifier "inherits" all features defined by its direct or indirect generalizations. A generalization, (a.k.a. supertype, superclass, extended class, implemented interface) is the opposite of specialization (a.k.a. subtype, subclass, interface implementations, "is a"). A classifier A is compatible to a classifier B if A is a (direct or indirect) specialization of B or, looking at the same fact from the other direction: B is a (direct or indirect) generalization of A. Every classifier implicitly or explicitly specializes Node from LionWeb’s built-in library.

Concepts are equivalent to classes in object-orientation. They can extend one other concept, and implement any number of interfaces. An abstract concept can never be instantiated, i.e. there cannot be a node with that classifier. An abstract concept can extend a concrete (i.e. abstract=false) concept, and vice versa. Concepts marked as partition can only appear as root nodes in a model (i.e. not have a parent).

Annotations are similar to concepts: They can extend one other annotation and implement interfaces. They are always concrete, and cannot be used as partition. Additionally, annotations describe which classifiers they are applicable to.

Interfaces can extend any number of other interfaces. They are always abstract, thus can never be instantiated.

Features are the possible contents of a classifier. LionWeb supports three kinds of features: properties are simple values, containments describe other nodes with shared lifetime, and references point to other nodes. We summarize the latter two as links.

Data types describe the possible values of a property. LionWeb supports three kinds of data types: primitive types with no further specified structure, enumerations with a finite, pre-defined, non-extensible list of possible values, and structured data types as combination of other data types.