Load specification

An example of artifact YAML definitions, lines 5+:

artifacts:
  reference-materials:
    name: Reference Materials
    description: Reference materials external to enterprise
    children:
      togaf-library:
        name: TOGAF Library
        documentation:
          content-markdown:
            source:
              content-text: "[TOGAF Library](https://publications.opengroup.org/togaf-library)"
      architecture-frameworks:
        name: Architecture frameworks
        documentation:
          content-markdown:
            source:
              content-text: Other architecture frameworks.
Type EString

Keys of accountable participants relative to the containing package participants/ reference.

Type EObject

If this reference is not set then EObjectActionProvider creates a new Action using AppFactory in newAction() method. If this reference is set and is Action then a copy of the action is created and returned. Otherwise the reference value it is adapted to ActionProvider which is used to create an action. This allows to merge actions and chain action generation. E.g. generate Ecore model documentation and merge it into the Engineering documentation.

Type ArtifactEntry

Artifacts can be organized into a hierarchy (Product Breakdown Structure).

Type EString

Keys of consulted participants relative to the containing package participants/ reference.

Type EString

Description in HTML.

Type EObject

Element documentation. Documentation elements are adapted to SupplierFactory<InputStream> during generation. Exec content classes such as Markdown and Interpolator can be used as documentation elements.

Examples

Plain text

Single line
documentation:
  content-text: Single line documentation
Multi-line
documentation:
  content-text: |+2
    Multi-line documentation, line 1
    Line 2.
Loaded from resource
documentation:
  content-resource: doc.txt

Markdown

Single line
documentation:
  content-markdown:
    style: true
    source:
      content-text: Single ``line`` documentation
Multi-line
documentation:
  content-markdown:
    style: true
    source:
      content-text: |+2
        Line 1.        
        **Line 2**.
Loaded from resource
documentation:
  content-markdown:
    style: true
    source:
      content-resource: doc.md
Type EString

Keys of informed participants relative to the containing package participants/ reference.

Type EString

A collection of boolean flags:

  • abstract - Specifies that this package element is abstract. For packages and flows it means that they contain abstract elements and must be extended to become concrete. If a package or a flow contains abstract elements and does not have abstract modifier, it is diagnosed as an error. If concrete packages and flows extend abstract ones they must override (implement) all abstract elements.
  • explicit-end - Applies to flows. Specifies that the end pseudo-state shall not be inferred by finding flow elements with no outputs. End will either be explicitly specified or the diagram will not have an end pseudo-state.
  • explicit-start - Applies to flows. Specifies that the start pseudo-state shall not be inferred by finding flow elements with no inputs. Start will either be explicitly specified or the diagram will not have a start pseudo-state.
  • final - Specifies that this flow element cannot be overridden in flows extending this flow. Overriding a final elemen will be diagnosed as an error. For example, in an organization some processes can be defined as flows at higher levels of the orgnization and extended at lower levels. final modifier allows to specify what can be extended and what cannot. Specifying a top-level flow as final indicates that it cannot have extensions.
  • optional - Specifies that this element is optional. Optional elements have different apperance on diagrams.
  • extension - Specifies that this element is an extension for an element in one of extended packages/flows. If this modifier is present and extends reference is empty, then it results in a diagnostic error.
  • partition - Applies to flows and specifies that a flow shall be rendered as a partition (e.g. a composite state) on a diagram.
Type EString

Element name.

Type RelationshipEntry
Homogenous true
Strict containment true

Outbound relationships to other artifacts. Artifact relationships can be used for modeling composite artifacts, e.g. modular/distributed systems such as cloud applications.

Type EBoolean

If true, this composite artifact shall be displayed as a partition on the parent component diagram.

Type Property
Homogenous true

Properties can be used to customize the documentation generation process, e.g. provide configuration for generation of representation diagram elements.

The below snippet shows how to use properties to customize diagram element shape for draw.io diagrams:

service-catalog:
  name: AWS Service Catalog
  properties:
    representation:
      drawio:
        width: 150
        height: 200
        style:
          shape: mxgraph.aws3d.cloudfront

Properties under the representation are copied to the representation diagram element. Then, properties under the drawio key are used during generation of draw.io diagrams. The following properties are supported by drawio diagram elements:

  • height - integer
  • width - integer
  • style - string or map

Properties with other keys become user object attributes.

Type EString

Keys of artifact’s repositories relative to the containing package resources/ reference.

Type RepresentationEntry
Homogenous true

Mapping of representation names to values - Diagrams which serve as templates for generating diagram content from the package element.

The below code snippet defines two representations:

  • flow with plantuml type (default).
  • generated with drawio type.
test:
  flow-flow:
    name: Test
    representations:
      flow:
        hide-empty-description: true
        vertical: false
      generated: 
        type: drawio:./test.drawio
        name: Drawio
        description: Generated diagram

In the second case a diagram file test.drawio is generated if it doesn’t exist. This file can be edited after generation using an online editor or a desktop application which can be downloaded from https://www.diagrams.net/.

The ./ prefix indicates that the diagram file location shall be resolved relative to the marker location, i.e. the location of the YAML file with representation definition. If there is no prefix, or if there is no marker, i.g. if the definition was loaded from XMI and not from YAML, then diagram file location is resolved relative to the model resource location, which may be different from the location of the YAML file.

Type EString

Keys of responsible participants relative to the containing package participants/ reference.

Type ActivityEntry

Services provided by a this service provider.

Type DiagramElement
Homogenous true

Diagram element style for component diagrams. If specified, the style diagram element is used as a template for a diagram element created to represent this artifact on a diagram.

The below code snippet provides several examples of style definition:

  artifacts:
    binary:
      name: Docker Image
      modifiers: extension
    kubernetes-cluster:
      name: Cluster
      partition: true
      representations:
        uml: {}
        drawio: 
          type: drawio:./cluster.drawio
      children:
        node-a: 
          name: Node A
          description: Web requests processing node
          partition: true
          style:
            type: node
            dashed: true
            color: lightblue
          children:
            container-1: 
              name: Container A.1
              partition: true
              children:
                httpd:
                  name: Apache Web Server
                  relationships:
                    tomcat:
                      target: ../../container-2/children/tomcat
                      description: Reverse proxy
                      name: Pass request
                      style:
                        type: "#-->>" 
            container-2: 
              name: Container A.2              
              partition: true
              children:
                tomcat:
                  name: Tomcat
                  style:
                    stereotype: Servlet Container
                    properties:
                      drawio:
                        width: 150
                        height: 200
                        style:
                          shape: mxgraph.aws3d.cloudfront
        node-b: 
          name: Node B
          style:
            type: node
          partition: true
          children:
            container-1: 
              name: Container B.1
            container-2: 
              name: Container B.2                        
  • Node A defines type as node with dashed border and light blue background.
  • A relationship from the Apache Web Server to Tomcat customizes its appearance using #-->> connection style. For details on styling of PlantUML diagram elements see PlantUML documentation.
  • Tomcat defines “Servlet Container” stereotype. It also defines style properties specific to drawio - height, width, and style as an AWS CloudFront icon.
  • Node B defines its style type as node.

Draw.io style properties

Defining style for Draw.io diagrams makes sense for template artifacts so their instances inherit the style. You can open the Draw.io/Diagrams.net editor either in the browser or desktop, create and style a diagram element, and then copy the style to YAML. You can do it in the editor by clicking Edit > Style and copying the style definition to YAML. You may copy it as a string or convert to YAML. You can also go to Extras > Edit diagram and, copy the XML definition and convert to YAML.

For example, this XML definition

    <mxCell
        id="C2D87RZH6g-nyLimbJug-1"
        value="CloudFront"
        style="verticalLabelPosition=bottom;html=1;verticalAlign=top;strokeWidth=1;align=center;outlineConnect=0;dashed=0;outlineConnect=0;shape=mxgraph.aws3d.cloudfront;fillColor=#ECECEC;strokeColor=#5E5E5E;aspect=fixed;"
        parent="1"
        vertex="1">
      <mxGeometry x="370" y="630" width="103.8" height="169.79999999999998" as="geometry" />
    </mxCell>

would correspond to this YAML definition:

style:
  properties:
    drawio:
      x: 370
      y: 630
      width: 103.8
      height: 169.79999999999998
      style: verticalLabelPosition=bottom;html=1;verticalAlign=top;strokeWidth=1;align=center;outlineConnect=0;dashed=0;outlineConnect=0;shape=mxgraph.aws3d.cloudfront;fillColor=#ECECEC;strokeColor=#5E5E5E;aspect=fixed;             

or this one, which is more readable:

style:
  properties:
    drawio:
      x: 370
      y: 630
      width: 103.8
      height: 169.79999999999998
      style: 
        verticalLabelPosition: bottom
        html: 1
        verticalAlign: top
        strokeWidth: 1
        align: center
        outlineConnect: 0
        dashed: 0
        outlineConnect: 0
        shape: mxgraph.aws3d.cloudfront
        fillColor: "#ECECEC"
        strokeColor: "#5E5E5E"
        aspect: fixed

You don’t need to specify element position (x and y) as it will be automatically positioned. You may also skip some style attributes which are not essential or have default values - experiment to find out which ones to keep and which ones to drop.

Type EString

Keys of artifact’s templates relative to the artifact URI.

uri

Type EString

If element’s URI is not set then its default value is derived from the container URI and containment reference. This is a logical URI and it can be used for cross-referencing of elements in a resource-independent fashion.

Type EString

Optional unique identifier for this model element. For root objects UUID is used to compute URI, if the URI is not set.