BAMM CLI

The BAMM CLI is a command line tool for the validation of Aspect models and the generation of artifacts, such as documentation or code, from Aspect models.

Download latest version: bamm-cli-2.1.0.jar

Running the BAMM CLI

For the executable jar, call java -jar bamm-cli-2.1.0.jar followed by one of the following subcommands (e.g., java -jar bamm-cli-2.1.0.jar help). In the following sections, bamm will be used as the command name.

To make bamm-cli easier to call, you can add an alias to the configuration of the shell of your choice. For example, for Bash, you could add the following line to .bashrc:

alias bamm='java -jar /location/to/bamm-cli-2.1.0.jar'

Successful execution of a command is signaled by returning 0. In case of logical or some other internal problem error code 1 is returned. Missing or wrong command parameters result in error code 2 being returned.

To get help for a certain subcommand, add 'help' before the subcommand name or add --help to the end, e.g., bamm help aspect or bamm aspect --help. Each subcommand can have its own set of options which allow the user to further fine-tune the execution of the command. The available options and their meaning can also be seen in the help text of the individual subcommands.

Command Description/Options Examples

help

Get overview of all commands

bamm help

help <subcommand>

Get help for a specific subcommand

bamm help aspect

aspect help <aspect subcommand>

Get help for aspect subcommands

bamm aspect help validate

aspect <model> validate

Validate Aspect Model

bamm aspect AspectModel.ttl validate

--custom-resolver : use an external resolver for the resolution of the model elements

bamm aspect AspectModel.ttl validate --custom-resolver myresolver.sh

aspect <model> prettyprint

Pretty-print Aspect Model

bamm aspect AspectModel.ttl prettyprint

--output, -o : the output will be saved to the given file

bamm aspect AspectModel.ttl prettyprint -o c:\Results\PrettyPrinted.ttl

aspect <model> migrate

Migrate Aspect Model to the latest BAMM version

bamm aspect AspectModel.ttl migrate AspectModel.ttl

--output, -o : the output will be saved to the given file

bamm aspect AspectModel.ttl migrate AspectModel.ttl -o c:\Results\MigratedModel.ttl

aspect <model> to html

Generate HTML documentation for an Aspect Model

bamm aspect AspectModel.ttl to html

--output, -o : the output will be saved to the given file

bamm aspect AspectModel.ttl to html -o c:\Model.html

--css, -c : CSS file with custom styles to be included in the generated HTML documentation

bamm aspect AspectModel.ttl to html -c c:\styles.css

--language, -l : The language from the model for which the HTML should be generated (default: en)

bamm aspect AspectModel.ttl to html -l de

--custom-resolver : use an external resolver for the resolution of the model elements

bamm aspect AspectModel.ttl to html --custom-resolver myresolver.bat

aspect <model> to png

Generate PNG diagram for Aspect Model

bamm aspect AspectModel.ttl to png

--output, -o : output file path (default: stdout); as PNG is a binary format, it is strongly recommended to output the result to a file by using the -o option or the console redirection operator '>')

--language, -l : the language from the model for which the diagram should be generated (default: en)

--custom-resolver : use an external resolver for the resolution of the model elements

bamm aspect AspectModel.ttl to png --custom-resolver resolver.jar

aspect <model> to svg

Generate SVG diagram for Aspect Model

bamm aspect AspectModel.ttl to svg

--output, -o : the output will be saved to the given file

--language, -l : the language from the model for which the diagram should be generated (default: en)

--custom-resolver : use an external resolver for the resolution of the model elements

bamm aspect AspectModel.ttl to svg --custom-resolver "java -jar resolver.jar"

aspect <model> to dot

Generate DOT diagram for Aspect Model

bamm aspect AspectModel.ttl to dot

--output, -o : output file path (default: stdout)

--language, -l : the language from the model for which the diagram should be generated (default: en)

--custom-resolver : use an external resolver for the resolution of the model elements

aspect <model> to java

Generate Java classes from an Aspect Model

bamm aspect AspectModel.ttl to java

--output-directory, -d : output directory to write files to (default: current directory)

--package-name, -pn : package to use for generated Java classes

bamm aspect AspectModel.ttl to java -pn org.company.product

--no-jackson, -nj : disable Jackson annotation generation in generated Java classes

--template-library-file, -tlf : the path and name of the Velocity template file containing the macro library

--execute-library-macros, -elm : Execute the macros provided in the Velocity macro library

--static, -s : generate Java domain classes for a Static Meta Model

--custom-resolver : use an external resolver for the resolution of the model elements

aspect <model> to openapi

Generate OpenAPI specification for an Aspect Model

bamm aspect AspectModel.ttl to openapi -j

--output, -o : output file path (default: stdout)

--api-base-url, -b : the base url for the Aspect API used in the OpenAPI specification

bamm aspect AspectModel.ttl to openapi -j -b http://mysite.de

--json, -j : generate a JSON specification for an Aspect Model (default format is YAML)

--parameter-file, -p : the path to a file including the parameter for the Aspect API endpoints

For detailed description, see the section bellow

--semantic-version, -sv : use the full semantic version from the Aspect Model as the version for the Aspect API

--resource-path, -r : the resource path for the Aspect API endpoints

For detailed description, see the section bellow

--include-query-api, -q : include the path for the Query Aspect API Endpoint in the OpenAPI specification

--paging-none, -pn : exclude paging information for the Aspect API Endpoint in the OpenAPI specification

--paging-cursor-based, -pc : in case there is more than one paging possibility, it has to be cursor based paging

--paging-offset-based, -po : in case there is more than one paging possibility, it has to be offset based paging

--paging-time-based, -pt : in case there is more than one paging possibility, it has to be time based paging

--custom-resolver : use an external resolver for the resolution of the model elements

aspect <model> to json

Generate OpenAPI JSON specification for an Aspect Model

bamm aspect AspectModel.ttl to json

--output, -o : output file path (default: stdout)

--custom-resolver : use an external resolver for the resolution of the model elements

aspect <model> to schema

Generate JSON schema for an Aspect Model

bamm aspect AspectModel.ttl to schema

--output, -o : output file path (default: stdout)

--custom-resolver : use an external resolver for the resolution of the model elements

aspect <model> to aas

Generate Asset Administration Shell (AAS) submodel template for an Aspect Model

bamm aspect AspectModel.ttl to aas

--output, -o : output file path (default: stdout)

--format, -f : output file format (xml or aasx, default: xml)

--custom-resolver : use an external resolver for the resolution of the model elements

Custom model resolver

To allow the users to provide their own custom implementations of a model resolver, --custom-resolver command-line switch can be used. The value of the switch can be any command which is directly executable by the underlying operating system (such as a batch script on Windows or a shell script on Linux/Unix). When a model element needs to be resolved, this command is executed with the URN of the element to resolve passed as the last parameter. The command can provide other parameters as well, the element URN will be added automatically as the last one by bamm-cli. The resolved model definition is expected to be output to the stdout in Turtle format. From there, it is read by the bamm-cli and passed on to the internal processing pipeline. In this way the extension can be flexibly done in any programming language/script language, including complex logic if necessary.

Using the CLI to create a JSON OpenAPI Specification

Every specification is based on one Aspect, which needs a separately defined server URL where the given aspect will be. The URL will be defined as string with the -b option, i.e.: https://www.example.org. The default URL, using the above defined --api-base-url, would result in https://www.example.org/api/v1/{tenantId}/<aspectName>;. By default the Aspect’s local name is used as path. The default path can be manipulated with the --resource-path switch. If the path is defined further, for example --resource-path "/resources/{resourceId}", the resulting URL would be: https://www.example.org/api/v1/{tenantId}/resources/{resourceId}.

It will be required to specify the parameter, in case there is an additional parameter defined. This has to be in JSON or in YAML, depending on the kind of specification chosen. For example: With the option --resource-path "/resources/{resourceId}" the generator constructs the URL https://www.example.org/api/v1/{tenantId}/resources/{resourceId} and then the --parameter-file defines the parameter resourceId in yaml:

resourceId:
  name: resourceId
  in: path
  description: An example resource Id.
  required: true
  schema:
    type: string

The full command would result in:

java -jar bamm-cli-2.1.0.jar aspect AspectModel.ttl to openapi -b "https://www.example.org" -r "/resources/{resourceId}" -p fileLocation

Understanding the models directory structure

An Aspect model file can contain an Aspect definition as well as other model elements that are defined in the same versioned namespace, as described in the Namespaces section of the specification. Additionally, it is possible to split one versioned namespace across multiple files, for example to define a Characteristic that is usable in multiple Aspects into its own file. In order for BAMM CLI to be able to resolve references to such externally defined model elements, the model files must be organized in a directory structure as follows:

namespace/version/name.ttl

where namespace corresponds to the hierarchical namespace that is part of the model element’s URN, e.g. com.mycompany.myproduct and version corresponds to the version of the namespace. The resulting directory structure then looks like the following:

models root
└── com.mycompany.myproduct
    ├── 1.0.0
    │   ├── MyAspect.ttl
    │   ├── MyEntity.ttl
    │   └── myProperty.ttl
    └── 1.1.0
        └── MyAspect.ttl

The name of the directory shown as models root above can be chosen freely. The BAMM CLI will resolve the file path relative to the input file by following the folder structure described above. Each of the files in the 1.0.0 directory should therefore have an empty prefix declaration such as @prefix : <urn:bamm:com.mycompany.myproduct:1.0.0#>.