Datamodel plugin: data model diagrams and attribute tables

Purpose

The “datamodel” plugin allows you to include UML data models in the document, represented in diagrams with their attributes described in text.

The datamodel plugin uses a model-view structure, allowing the separate definition of the models themselves and the views that render them.

Metanorma’s “Datamodel YAML format” let you:

• Define UML models (“Model yaml”)

• Create diagrams that utilize those models (“View yaml”)

Metanorma provides two macros for this purpose:

• datamodel_attributes_table for generating model attributes in table form;

• datamodel_diagram for generating UML diagrams.

Model definition

Model YAML specification

The Model YAML format covers the following UML elements:

• Class

• Attribute, AttributeCardinality

• Relation, Relationship, RelationshipEnd, RelationshipEndAttribute, RelationAction

Class / Top-level

YAML Key	Data type	Required?	Description
name	String	false	Defaults to <model_name> (name of the Model YAML File).
modelType	Enum{"class", "enum"}	true	An enumeration value to specify the type of model.
type	String	false	Defaults to empty. If specified, stereotype of the model in UML. [example] .Example of a stereotype ==== In class System [Singleton], Singleton is the stereotype of the class, i.e. the value of this key. ====
definition	AsciiDoc	false	Defaults to empty. Textual definition of this model in Metanorma AsciiDoc.
attributes	Map<String, ModelAttribute>	false	Collection of attributes of this class. Value of this key is a map of attribute names to ModelAttribute objects.
values	Map<String, EnumValue>	Conditional	Only for models of modelType as enum and must be set in this case.
relations	Array<Relation>	false	Collection to specify the association of a model to another model.

Attribute

YAML Key	Data type	Required?	Description
definition	AsciiDoc	false	Defaults to the text “TODO: <todo_message>”. Textual description shown as definition in the attributes table for this attribute.
type	String	true	Name of another model to specify the data type of this ModelAttribute object.
cardinality	AttributeCardinality	false	The min/max occurrences of the attribute.

AttributeCardinality

YAML Key	Data type	Required?	Description
min	Integer/String	false	Minimum cardinality of this attribute. Defaults to 1. The String value of * denotes infinite occurrences.
max	Integer/String	false	Maximum cardinality of this attribute. Defaults to 1. The String value of * denotes infinite occurrences.

Relation

YAML Key	Data type	Required?	Description
target	String	true	Name of the associated model. MUST match name of the associated model for proper association in UML.
relationship	Relationship	false	Specifies the actual relationship between the source and target model.
action	RelationAction	false	Specifies the label on relations in a UML relationship.

Relationship

YAML Key	Data type	Required?	Description
source	RelationshipEnd	false	Specifies the actual relationship of the source model to the target model.
target	RelationshipEnd	false	Specifies the actual relationship of the target model to the source model.
association	String	false	Type of the intermediate model between the source model and the target model.

RelationshipEnd

YAML Key	Data type	Required?	Description
type	Enum{"inheritance", "aggregation", "composition", "direct"}	false	Specifies the type of association in UML.
attribute	Map<String, RelationshipEndAttribute>	false	Specifies the attribute of association in UML. Key value pair where the key is the attribute name and the value is the data of the attribute.

RelationshipEndAttribute

YAML Key	Data type	Required?	Description
cardinality	AttributeCardinality	false	Specifies the min/max occurrences of the attribute.

RelationAction

YAML Key	Data type	Required?	Description
verb	String	true	Specifies the text of the label in UML.
direction	Enum{"source", "target"}	true	Specifies the direction of the arrow of the label in UML.

Rendering the data model attribute table

The datamodel_attributes_table command generates a table of all attributes of a certain class in a Model YAML.

[datamodel_attributes_table,{YAML file path}]

Where:

• {YAML file path} is the location of the YAML file that contains model to be represented. Location of the YAML file is computed relative to the source directory that [datamodel_attributes_table] is used (e.g., if [datamodel_attributes_table,data.yaml] is invoked in an .adoc file located at foo/bar/doc.adoc, the data file is expected to be found at foo/bar/data.yaml).

The command transforms the given model YAML file into the following format:

=== {name || file_name }
{definition}

.{name || file_name } attributes
|===
|Name
|Definition
|Mandatory/ Optional/ Conditional
|Max Occur
|Data Type

|{attribute.name}
|{attribute.definition || "TODO: enum " + attribute.name + "'s definition"}
|{"O" || "M"}
|{"N" || "1"}
|{attribute.origin}`{attribute.type}`
|===

.{name || file_name } values
|===
|Name
|Definition

|{value.name}
|{value.definition}
|===

Where:

• {name}, {definition} - attributes with the same name from supplied YAML model file

• {file_name} - name of the model YAML file without the extension.

• {attribute} - element of attributes list from YAML file(if one is present)

• {value} - element of values list from YAML file(if one is present)

• {"O" || "M"} - depending on attribute’s element cardinality.min field, if cardinality.min equal to 0 then O else M

• {"O" || "M"} - depending on attribute’s element cardinality.max field, if cardinality.max equal to * then N else 1

View definition

View YAML specification

The View YAML format is used to specify diagrams using Model YAMLs.

Top-level

YAML Key	Data type	Required?	Description
name	String	true	Unique name to identify this diagram for internal processing.
caption	AsciiDoc	false	Specifies the caption under the image of the diagram in the document.
imports	Map<String, ModelFidelity>	false	Map between model YAML paths (<model_path>/<model_name>) and “Model Fidelity” objects. The specified models in the model YAML paths will be imported into this diagram.
relations	Array<Relation>	false	A collection of relations in this diagram. Used to aid rendering of the models by specifying hidden lines with direction.
fidelity	ViewFidelity	false	Specifies the type of details to be rendered in the diagram.

ModelFidelity

YAML Key	Data type	Required?	Description

RelationAction

YAML Key	Data type	Required?	Description
target	String	true	Name of the associated model. This must match the name of the associated model to be properly associated in UML.
relationship	Relationship	false	Specifies the relationship between the source and target model.
action	RelationAction	false	Specifies the label on relations in UML.

ViewFidelity

YAML Key	Data type	Required?	Description
hideMembers	Boolean	false	Specifies whether model attributes and their definitions should be rendered in the diagram.
hideOtherClasses	Boolean	false	Specifies whether related models other than the imported ones should be rendered in the diagram.

Rendering the data model diagram in the document

The datamodel_diagram command renders a UML diagram specified in a View YAML file.

[datamodel_diagram,{YAML file path},{include path}]

Where:

• {YAML file path} is the location of the View YAML file. Location of the YAML file is computed relative to the source directory that [datamodel_diagram] is used (e.g., if [datamodel_diagram,data.yaml] is invoked in an .adoc file located at /foo/bar/doc.adoc, the data file is expected to be found at /foo/bar/data.yaml);

• {include path}, optional attribute that tells where to find models file to import (imports key).

The caption key in the View YAML file will be used as caption text for diagram image figure, if available.