Metanorma: Aequitate Verum

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.