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:

datamodelattributestable 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 datamodelattributestable 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 [datamodelattributestable] is used (e.g., if [datamodelattributestable,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
{"N" || "1"} - 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.

Edit this page on GitHub →