diff --git a/documentation/BAMM-method-documentation,-tool-and-training.md b/documentation/BAMM-method-documentation,-tool-and-training.md new file mode 100644 index 00000000..7a754f72 --- /dev/null +++ b/documentation/BAMM-method-documentation,-tool-and-training.md @@ -0,0 +1,131 @@ +**BAMM method documentation, tool and training** + +For general introduction to BAMM refer the official website of [Open Manufacturing Platform] (https://openmanufacturingplatform.github.io/sds-documentation/bamm-specification/snapshot/index.html) + + +**BAMM Modeling methodology Digital Twins** + +**Introduction** + +A Digital Twin System forms the basis for comprehensive digitization of production and logistics by gradually creating consistent data homogeneity and interoperability. + + +![image](https://user-images.githubusercontent.com/105782625/188820652-cdeacad3-8a63-41ce-888d-0041c87f1a39.png) + + +Any asset — it can be an actual physical asset like a drilling machine but also something virtual like a web service — has a digital representation with consistent semantics, called a Digital Twin. Digital Twins represent those assets and services and provide a shell for their Aspects which define the functionality the Digital Twin supports. Aspects provide the actual data of the Digital Twin that clients can use. Think of an Aspect as a live thing, i.e., a service that can be queried to retrieve current or aggregated data. The data can be anything from a single numeric value — e.g., a temperature sensor — to a complex block of data. +Each Aspect references a concrete Aspect Model. This model describes in a formal, i.e., machine readable, format, how an Aspect is structured and what the data actually means. The model describes for example the used physical unit and possible value range of the temperature sensor. Note that even in this simple example, a conventional approach could not satisfyingly answer the question of where this kind of information would otherwise live — in the sensor’s data sheet that is only a human-readable document? In the Aspect’s API documentation that is also only human-readable? Should the information about the sensor’s physical range be hard-coded in the Aspect and included in each service reply, even though it never changes? By expressing it in the Aspect model, the Aspect’s semantics can be made available to consumers of the data in a way that opens up new possibilities. + +Therefore, an Aspect model contains both information about runtime data structure (e.g., that there is a property in the data called "temperature", and that it has a numeric value) and information that is not part of the runtime data (e.g., the unit or range). It does not, however, contain actual runtime data (e.g., a numeric value representing the current temperature), as this will be delivered by an Aspect conforming to this Aspect model. The combination of raw runtime data and its corresponding Aspect model yields information. +To specify an Aspect Model, the BAMM Aspect Meta Model (BAMM) [[bamm](https://openmanufacturingplatform.github.io/sds-bamm-aspect-meta-model/bamm-specification/snapshot/index.html)] is used. + + +**Illustration of using BAMM for Digital Twin Modeling** + +The models describe so called aspects of a digital twin. A digital twin is a digital representation of a physical asset, which might expose different data and operations. Depending on what a business application is interested in, different values and operations might be relevant, which often can be grouped. Such groupings can be modeled with Aspect models. + +An Aspect model describes what data and operations can be accessed. An aspect model is instantiated for a concrete digital twin (cf represents a concrete physical asset) and will provide you with the specified properties and operations. + +An example: As a physical asset you have a concrete gearbox. For the gearbox a digital twin is defined which in our case consists of the two aspects Material and ProductDescription. + +The actual implementation of these Aspects is done via – for example – a web-service which provides the actual data for the aspect of the specific gearbox. So with the Aspect model we express the structure and semantics of the data coming from that data source. The APIs of the two web services for both aspects could look like the following (generated with the OMP BAMM SDK) + + + + + +The web services that implement the aspects can then be used by a business application that provides an overview of the materials within the gearbox. The business application requests the required data for the specific gearbox from such a web service in the format that the Aspect Model defines. The return values of a get request for the ProductDescription aspect would look like this + + + + + + + +In this example the digital twin would provide the business application with the references (URI, etc.) to this specific data source for the Aspects. + + + + + +![image](https://user-images.githubusercontent.com/105782625/189339059-06162b64-4828-4cd6-82fc-8d72855f34d2.png) + + + + + +The interaction with the digital twin looks like in the following UML sequence diagram. + + +![image](https://user-images.githubusercontent.com/105782625/188822403-bfdcde5d-7dba-4a66-ba2a-3f62d92979f8.png) + + + +Conversely – but not illustrated in the picture above – an aspect can also describe operations of a digital twin. In that case a business application would not request data from an Aspect-implementing web service but rather call an operation to trigger some behavior of the digital twin. An example, but not related to the example from the actual CE use case above, an aspect could provide an operation to move a robot arm to a certain position in space. + +**_General Remarks to BAMM_** + +BAMM is specified by the Open Manufacturing Platform. the BAMM Specification can be found [here](https://openmanufacturingplatform.github.io/sds-bamm-aspect-meta-model/bamm-specification/snapshot/index.html). The specification contains also an introduction to the modeling elements of BAMM. For an introduction of the model elements and its use, please have a look [here](https://openmanufacturingplatform.github.io/sds-bamm-aspect-meta-model/bamm-specification/snapshot/modeling-guidelines.html). The general structure of a BAMM model is, that it defines one Aspect of a digital twin, which exposes one or more properties, whose data type and semantics are specified with a Characteristic. A Characteristic can be reused among properties. For details please have a look into the specification and the modeling guide for an in depth explanation of the modeling elements. + +The Meta Model is specified using the Resource Description Format (RDF, [[rdf11]](https://openmanufacturingplatform.github.io/sds-bamm-aspect-meta-model/bamm-specification/snapshot/appendix/appendix.html#rdf11)) and the Terse RDF Triple Language syntax (TTL, [[turtle]](https://openmanufacturingplatform.github.io/sds-bamm-aspect-meta-model/bamm-specification/snapshot/appendix/appendix.html#turtle)), together with validation rules in the Shapes Constraint Language (SHACL, [[shacl]](https://openmanufacturingplatform.github.io/sds-bamm-aspect-meta-model/bamm-specification/snapshot/appendix/appendix.html#shacl)). Aspect models are likewise specified in RDF/Turtle, following BAMM semantics [[bamm](https://openmanufacturingplatform.github.io/sds-bamm-aspect-meta-model/bamm-specification/snapshot/index.html)]. + +Based on the Meta Model an SDK is provided by the Open Manufacturing Platform, which can be used to realize digital twins and their aspect implementations. The SDK can be found [here](https://github.com/OpenManufacturingPlatform/sds-sdk). + +**Modeling Approach** + +The modeling of Aspects of Digital Twins most likely will happen in the broader context of an digitalization effort, which implies that basically two approaches – top-down or bottom-up – to identify and model Aspects are possible. In the top-down modeling process, you start with the idea for an Aspect model but have no prior data model (e.g. JSON structure). In the bottom-up modeling process, you start with an existing data model, i.e. you already have a REST service and you want that the data provided by an aspect matches an existing JSON structure. + +Generally, the top-down should be preferred as it usually yields better structured models that do not make concessions towards an already existing implementation and by that better reflect the actual domain. + +Top-Down Approach: + +1. Collect and understand the data that needs to be contained in Aspects +> a. Questions to be answered: Is it relevant? How is it going to be used? + +> b. Avoid bloating models with Properties or other structure that "might be needed at some point". Model evolution should be preferred over adding a lot of structure upfront. + +> c. Consider creating a rough (informal) domain model draft or concept map to validate a shared understanding with the expert(s) + +2. Separate data into Aspects to maximize [cohesion](https://en.wikipedia.org/wiki/Cohesion_(computer_science)) and reusability +> a. There is no single "correct" way to separate data into Aspects, but one rule of thumb is to put those Properties together into one Aspect model that most likely are going to be queried together at runtime + +3. Decide on the meta data of the model +> a. Pick a descriptive but concise model name + +> b. Pick a version for the model. If this is the first version, start with 1.0.0 + +> c. Pick a namespace for the model + +4. Analyze each designated Property in your model draft +> a. Give the Property a speaking name. + +> b. Can a predefined [Characteristic instance](https://openmanufacturingplatform.github.io/sds-bamm-aspect-meta-model/bamm-specification/v1.0.0/characteristics.html#characteristics-instances) be used for the Property, or one of the predefined [Characteristics classes](https://openmanufacturingplatform.github.io/sds-bamm-aspect-meta-model/bamm-specification/v1.0.0/characteristics.html#characteristics-classes) be instantiated? + +> c. It is always preferable to use something that is already there. It makes the model easier to understand and the resulting Aspect easier to use. For example, the SDK might already offer some convenience for Characteristic instances in implementations and solutions. + +5. Add [Constraints](https://openmanufacturingplatform.github.io/sds-bamm-aspect-meta-model/bamm-specification/v1.0.0/characteristics.html#constraints) to the Characteristic as necessary. + +6. Complete the model +> a. Define example values where it makes sense + +> b. Add proper descriptions and preferred names, at least in English + +> c. Check names and descriptions for typos and grammar mistakes + + +Bottom-Up-Approach: + +In the bottom-up modeling process, you start with an existing data model, i.e. you already have a REST service and you want the payload structure that follows the Aspect model to match the existing JSON structure. This might be necessary when you want to make the existing service a valid Aspect but can not or want not change its data structure. + +The existing data structure replaces the model draft as compared to the top-down modeling process. + +1. Enter step 3 from the top-down modeling process + +2. When defining a Property, you should use the name of the existing corresponding key in the data structure to allow for a one to one mapping between Aspect model and JSON structure. + +3. Make sure that the resulting Aspect-model yields the same JSON document structure as the son-document initially used to model the Aspect model. + +Note: When building an Aspect model to match an existing data structure, there may be mismatches in the defined value spaces of the Characteristics used in the model and the runtime data provided by the Aspect. For example, you might want to define a Property timestamp and use the existing [Timestamp](https://openmanufacturingplatform.github.io/sds-bamm-aspect-meta-model/bamm-specification/v1.0.0/characteristics.html#timestamp-characteristic) Characteristic, but the existing data model expects numeric values (i.e. [numbers of seconds](https://en.wikipedia.org/wiki/Unix_time)), while the Timestamp Characteristic has a dataType of xsd:dateTime which in turn expects values such as "2000-01-01T14:23:00". Mismatches like this can either be resolved in the model (i.e. do not use the Timestamp Characteristic) or in the Aspect implementation (e.g. by on-the-fly conversion of values). Either way, the provided runtime value must match the Characteristic of the Property in the model. + +Using BAMM for Aspect Modelling +Example models can be found here [Getting Started with Aspect Modeling based on BAMM](https://github.com/Sujit-Kumar-ZF/sldt-semantic-models/wiki/Getting-Started-with-Aspect-Modeling-based-on-BAMM). \ No newline at end of file diff --git a/documentation/Getting-Started-with-Aspect-Modeling-based-on-BAMM.md b/documentation/Getting-Started-with-Aspect-Modeling-based-on-BAMM.md new file mode 100644 index 00000000..d21c6d92 --- /dev/null +++ b/documentation/Getting-Started-with-Aspect-Modeling-based-on-BAMM.md @@ -0,0 +1,268 @@ +The intention of the following page is to give an introduction on modeling an aspect model based on the BAMM Aspect Meta Model. + +**Prerequisites** + +For the first part of this guide, you do not require any pre requisites installed on your machine since it stays on the conceptual level. But we recommend that you follow the modeling steps on your machine which can be done with every text editor (e.g. VS Code, Notepad++, Emac, VI). + +When interacting with created aspect models you need the BAMM CLI and an installation of the Java Runtime to execute the BAMM CLI. References on on how to download install both are given below. + +**Motivation** + +With an aspect model one can describe the structure and semantics of data that is coming from a data source. This data source can also be referred to as the aspect implementation. The aspect model and an aspect implementation together form an aspect. With this interpretation each aspect model may match with multiple aspect implementation that each conform to the interface defined by the aspect model. Thus creating the aspect model is a good way to exchange and reach agreement on the data to expect and the meaning of that data. + +To establish a common and inter-operable understanding of the definition in an aspect model that can also be interpreted by a computer, one needs to agree on the way the aspect models are expressed. In other more colloquial words, we need a meta model to agree on a common vocabulary and language for describing aspect models. The aim of the BAMM Aspect Meta Model is to be such a meta model for expressing aspect models. BAMM itself is defined and maintained as [open source in the Open Manufacturing Platform](https://github.com/OpenManufacturingPlatform/sds-bamm-aspect-meta-model) . In conjunction to the elements defined in BAMM, there are [additional libraries and tooling](https://github.com/OpenManufacturingPlatform/sds-sdk) to make the interaction with aspect models that are based on BAMM easier. + +The following guide, first introduces the general process of writing an aspect model based on BAMM based one a simple example use case. In a second step we show how to use the tooling around BAMM to interact with the aspect models. + +**Use Case** + +Let's assume we have an AGV (Autonomous Guided Vehicle) which is moving. This AGV then communicates its movement information to a database from which we can retrieve the current movement state. This database would then be an aspect implementation. For that aspect implementation we now want to develop an aspect model describing the aspect of movement for the AGV. + +Our domain expert gave us the following JSON data for the data returned by the aspect implementation (database): + +``` +{ + + "moving" : true, + + "speedLimitWarning" : "green" + +} +``` + +In addition, we get the following information: + +> 1. The field "moving" is Boolean and can thus either be true or false +> 2. The speed limit warning can either be : + +![image](https://user-images.githubusercontent.com/105782625/188839448-759cae76-e75b-4820-ba2f-5cf51dcc8058.png) + +**Aspect Model**: + +As explained above, we want to come up with the aspect model for the Movement Aspect of the AGV. We can express this model in the form of a [Turtle](https://www.w3.org/TeamSubmission/turtle/) file. Turtle is file format which allows the expression of RDF graphs in natural text form. This allows the usage of the aspect model also for more elaborate use cases involving and queries. But while getting started with modeling it is not necessary to understand the implications of using Turtle files and RDF for the modeling and we will show how a basic Turtle files for aspect models could look like in the following. + +**BAMM** + +The aspect models that we are going to write, are based on the elements defined in the [BAMM Aspect Meta Model](https://openmanufacturingplatform.github.io/sds-documentation/bamm-specification/snapshot/meta-model-elements.html) . For this guide no prior knowledge of BAMM and its elements is required as the intention of this guide is to introduce the most relevant concepts and elements defined in BAMM. However, if you want to know more details, we recommend that you consult the [BAMM documentation](https://openmanufacturingplatform.github.io/sds-documentation/bamm-specification/snapshot/meta-model-elements.html). The following graphic gives an overview of the main elements in BAMM: + + +![image](https://openmanufacturingplatform.github.io/sds-documentation/bamm-specification/snapshot/_images/aspect-meta-model.svg) + + +**Modeling** + +For the modeling you can use any text editor like for example VS Code, Notepad, vi and so on and then later save the model file with the subfix .ttl. To get started open your favorite editor and enter the following text, which is the beginning of our aspect model: + +**Start of Movement.ttl** + +``` +@prefix : . +@prefix bamm: . +@prefix unit: . +@prefix bamm-c: . +@prefix bamm-e: . +@prefix xsd: . +@prefix rdfs: . + +:Movement a bamm:Aspect ; + bamm:name "Movement" ; + bamm:preferredName "Movement"@en ; + bamm:description "Aspect for movement information"@en ; + bamm:properties ( :isMoving :speedLimitWarning) ; + bamm:operations ( ) . +``` + +Let's see what is happening here. The Turtle files start with the definition of a couple of prefixes defining shortcuts for several URNs. For instance, :Movement then actually translates urn:bamm:com.catenax:0.0.1#Movement as the : is a placeholder for the actual urn (in our case . This way we can also reference the elements defined in BAMM (prefix bamm, prefix unit, prefix bamm-c, or prefix bamm-e). These prefixes are known and can be resolved by to the tooling around BAMM mentioned below. + +The definition of the actual Aspect starts in line 9 by stating: ":Movement a bamm:Aspect". This defines that the Movement is an Aspect element defined in BAMM. An Aspect element is the entry point of each aspect model. The next lines adds additional information on the Aspect. For more details on the different fields one can check the [documentation of an Aspect](https://openmanufacturingplatform.github.io/sds-documentation/bamm-specification/snapshot/modeling-guidelines.html) . + +The bamm:name is the name of the aspect and should only contain alphabetic or numeric characters and no whitespaces. The reason is that this name may be used as a property name in a programming code that gets generated based on the aspect model. Next, there are the "preferredName" and the "description". Both fields are intended to be interpreted by humans and may be used in user interfaces and similar systems and should be human-readable. For internationalization, it is possible to state them in multiple languages which are then identified by the tag after the `@`sign. In general, we advise you to at least state the English version and then add other languages whenever required. + +The fields described so far, exist in all elements defined in BAMM. The fields for bamm:operation and bamm:properties are specific to Aspects. + +The operation allows to express that the Aspect can compute an output based on a given input. To limit complexity, our example Movement Aspect does not allow any input from the user of the Aspect and we leave the list in bamm:operations empty here. One example in which we could have defined an operation would be if we extended our aspect implementation with a functionality to send a desired speed to the AGV. It would then be the task of the aspect implementation and thus in the end of the AGV to process this information. Optionally this processing could result in the return value like for example a boolean indicating whether the speed adjustment was performed successfully. + +The bamm:properties is a list referencing the Properties of the Aspect. In Aspect models, a Property represents a value or in other words, indicates the presence of a data value. The following excerpt shows how we could model the Properties in our use case: + +**Properties in Movement.ttl** + +``` +:isMoving a bamm:Property ; + bamm:name "moving" ; + bamm:preferredName "moving"@en ; + bamm:description "Flag indicating if the position is changing"@en ; + bamm:characteristic bamm-c:Boolean . + + +:speedLimitWarning a bamm:Property ; + bamm:name "speedLimitWarning" ; + bamm:preferredName "speedLimitWarning"@en ; + bamm:description "An indicator for the warning regarding the speed limit"@en ; + bamm:characteristic :speedLimitWarningCharacteristic . +``` + +As we can see in the excerpt, the structure for defining a Property has many similarities to the definition of the Aspect element and does again include the fields bamm:name, bamm:preferredName, bamm:description, bamm:characteristic . Note, that the entries for bamm:name match the names of the fields in the initial JSON file. + +An important point here is that the property only indicates the existence of a value, but does not define how the expected value type looks like. In BAMM this is separated into another model element, namely the Characteristic. This is the reason why the Property has a field bamm:characteristic to reference to the type information defined in a Characteristic. + +As explained above, our domain expert told us that :isMoving is of type Boolean. As this is a more easy and generic data type it has already been defined in BAMM and we can simply reuse and reference it by writing bamm-c:Boolean. Under bamm-c, one can reference several characteristics and types of Characteristics. For more details check the [documentation on Characteristics](https://openmanufacturingplatform.github.io/sds-documentation/bamm-specification/snapshot/characteristics.html). + +For the :speedLimitWarning we need to define our own :speedLimitWarningCharacteristic because it is specific to our Aspect model: + +**Characteristics in Movement.ttl** + +``` +:speedLimitWarningCharacteristic a bamm-c:Enumeration; + bamm:name "speedLimitWarningCharacteristic"@en; + bamm:description "Possible values for a speed limit warning, with the following meaning: green - under speed limit, yellow - at speed limit, red - over speed limit."@en; + bamm:dataType xsd:string; + bamm-c:values ("green" "yellow" "red") . +``` + + +The most generic way of defining a Characteristic would have been to write ":speedLimitWarningCharacteristic a bamm:Characteristic" . But we already know that the value of our speed limit warning will come from a list of predefined possible values. In BAMM there is already the special Characteristic called Enumeration for the cases where you can state the possible values. This is also the reason for writing "bamm-c:Enumeration" and not "bamm:Enumeration" as in the "bamm:Property", "bamm:Aspect", or "bamm:Characteristic". + +For the Enumeration, we need to define the basic dataType which in our case is String. More details on possible data type or how to define a custom data Type with an Entity is available under [Data Types in the BAMM documentation](https://openmanufacturingplatform.github.io/sds-documentation/bamm-specification/snapshot/datatypes.html). In :bamm-c:values we then give a list with the possible values. + +This already concludes the basic definition of the Aspect model for the Movement Aspect. Here is the complete model for reference which you could also copy to your editor (e.g., when starting to work with the BAMM CLI): + +![image](https://user-images.githubusercontent.com/105782625/188840310-e20dfcd0-effc-4cc0-8ed7-a28e352a591c.png) + +**Movement.ttl (complete)** + +``` +@prefix : . +@prefix bamm: . +@prefix unit: . +@prefix bamm-c: . +@prefix bamm-e: . +@prefix xsd: . +@prefix rdfs: . + +:Movement a bamm:Aspect ; + bamm:name "Movement" ; + bamm:preferredName "Movement"@en ; + bamm:description "Aspect for movement information"@en ; + bamm:properties ( :isMoving :speedLimitWarning) ; + bamm:operations ( ) . + +:isMoving a bamm:Property ; + bamm:name "moving" ; + bamm:preferredName "moving"@en ; + bamm:description "Flag indicating if the position is changing"@en ; + bamm:characteristic bamm-c:Boolean . + + +:speedLimitWarning a bamm:Property ; + bamm:name "speedLimitWarning" ; + bamm:preferredName "speedLimitWarning"@en ; + bamm:description "An indicator for the warning regarding the speed limit"@en ; + bamm:characteristic :speedLimitWarningCharacteristic . + + +:speedLimitWarningCharacteristic a bamm-c:Enumeration; + bamm:name "speedLimitWarningCharacteristic"@en; + bamm:description "Possible values for a speed limit warning, with the following meaning: green - under speed limit, yellow - at speed limit, red - over speed limit."@en; + bamm:dataType xsd:string; + bamm-c:values ("green" "yellow" "red") . +``` + + +**Tooling & BAMM CLI:** + +During the development of a new Aspect model, one can get support from tools such as the BAMM CLI (BAMM Command Line Interface). The BAMM CLI is software which does not have a visual user interface and can be executed through the [Terminal](https://en.wikipedia.org/wiki/Shell_%28computing%29) of your computer (e.g., cmd in Windows or Terminal in MacOS). + +The BAMM CLI has multiple features supporting the development of Aspect models and allowing the generation of artifacts like PNG images or HTML documentations based on the developed Aspect model. For more details and the download link to the BAMM CLI, visit the the [documentation](https://openmanufacturingplatform.github.io/sds-documentation/sds-developer-guide/tooling-guide/bamm-cli.html) or the [respective GitHub repository](https://github.com/OpenManufacturingPlatform/sds-sdk/tree/main/tools/bamm-cli). + +The BAMM CLI uses the implementation from the [SDS SDK](https://github.com/OpenManufacturingPlatform/sds-sdk). The SDS SDK is a collection of libraries interacting with Aspect models and gets maintained by the SDS WG (Semantic Data Structuring Working Group) in the [Open Manufacturing Platform](https://open-manufacturing.org/get-involved/). + +**General Usage** + +The BAMM CLI gets distributed as JAVA JAR-File, which is a distribution format for applications written in the JAVA programming language. That is also the reason why one needs an instance of the Java (Runtime) installed in the machine which also is part of the JDK (Java Development Kit). The terminal through which you execute the BAMM CLI also needs to have access to the Java Runtime. The [Adopt OpenJDK](https://adoptopenjdk.net/index.html) and its [installation guide](https://adoptopenjdk.net/installation.html) or are a good staring point to get Java up and running. However, the way you want to install Java strongly depends on your local setup and personal preference like the used operating system or Java distribution and a quick web search should return a couple of results for your specific environment . + +Once you installed Java and downloaded the BAMM CLI, it is possible to start the BAMM CLI by executing the following command in the terminal in the directory where the BAMM CLI is located: + +java -jar bamm-cli-version.jar + +You need to replace the version with a specific version of the BAMM CLI that you are using. The command should then output some information on the possible usage options for the BAMM CLI. In the following, we will go through a couple of these options. + +Import file (-i) +To allow the BAMM CLI to perform operations on an Aspect model, we first need to let the BAMM CLI load the model file. With the parameter -I one tells the BAMM CLI the location for the developed Aspect mode file. + +So the full command for importing the file would be: + +java -jar bamm-cli-version.jar -i //NameOfAspect.ttl + +The BAMM CLI assumes a specific folder structure for the file system where the aspect model is stored. This structure follows the namespace and the version in the URN of the model elements. In our Movement aspect example the beginning of the URN would be: (see line with "@prefix : "). The resulting recommended and expected folder structure is then the / which leads in our example to the structure com.catenax/0.0.1. For more details on the expected file structure visit the [BAMM CLI documentation](https://openmanufacturingplatform.github.io/sds-documentation/sds-developer-guide/dev-snapshot/tooling-guide/bamm-cli.html#models-directory-structure). Note, that BAMM CLI may allow folder names other than the namespace, if the imported files does not contain references to custom model elements that are defined in other files. + +The following screenshot shows, how the folder structure could look like for our example aspect: + +![image](https://user-images.githubusercontent.com/105782625/188840603-6c7abd33-fe75-4f5a-9a88-bd108dfceacd.png) + +**Validate** + +An essential step, especially during the development of an Aspect model, is to validate whether the model complies with the underlying meta-model. One can perform the validation by adding the option -v: + +java -jar bamm-cli-version.jar -i //NameOfAspect.ttl -v + +If the model is valid, the BAMM CLI will print "Validation report: Input model is valid" as shown in the following screenshot: + +![image](https://user-images.githubusercontent.com/105782625/188840792-490b219b-b95a-4030-87cd-75fa8b20649d.png) + +If the model is not valid, the BAMM CLI will print the validation error which then looks like in the next screenshot: + +![image](https://user-images.githubusercontent.com/105782625/188840877-5d57f958-c3ca-4173-8858-5ed46bd02c99.png) + +Try to make a guess, what could have been the issue here. + +In this case, the error was that the value/object for the preferredName in line 11 was missing the language tag. Similar to the description in line 12, it was "@en" in the valid model to indicate, that the string is in English language. + +![image](https://user-images.githubusercontent.com/105782625/188840929-08913afa-03b7-4733-b50e-9a41ce4fd940.png) + +**Generate PNG** + +A good way for getting an overview of the structure and the elements in the Aspect model is to generate a graphical representation. In the case of the BAMM CLI, this is possible in the form of a PNG image by adding the option -png : + +java -jar bamm-cli-version.jar -i //NameOfAspect.ttl -png + +![image](https://user-images.githubusercontent.com/105782625/188841037-4b5fa116-18d2-42ff-bbd8-8b83c96bad67.png) + +For the Movement Aspect introduced above the picture then is: + +![image](https://user-images.githubusercontent.com/105782625/188841091-d668adda-6975-46cb-b7e3-23a6af4b5f7f.png) + + +**Generate HTML** + +It is also possible to generate HTML documentation for the Aspect model. This makes the description information from the aspect model available in a more human-readable and accessible form. To generate an HTML documentation add the option -html : + +java -jar bamm-cli-version.jar -i //NameOfAspect.ttl -html + +In the default configuration, the BAMM CLI uses a style that is influenced by the Open Manufacturing Platform since the BAMM CLI is maintained in the scope of that organization. However, it is possible to use a custom style to adapt to the use case by adding the option -hccf ( --html-custom-css-file) to specify an alternative CSS file for the styling. For Catena-X we already created [a CSS file](https://github.com/catenax/tractusx/blob/main/semantics/semantic-hub/src/main/resources/catena-template.css) that applies the logo and coloring scheme to the generated HTML documentation. + +In general, we advise using "self-contained" CSS files which do not reference external files. In the given examples, we achieved this by adding the logos directly to the CSS files as a base64 encoded block. + +**Generate JSON** + +Another option of the BAMM CLI is to generate a JSON with an example payload that conforms to the described Aspect model. This example may be helpful when checking whether the Aspect model aligns with already available test data or when one wants to generate additional test data. One can create the example JSON with the option -json : + +java -jar bamm-cli-version.jar -i //NameOfAspect.ttl -json + +For the Movement Aspect such a JSON would look like the following: + +``` +{ + "moving" : true, + "speedLimitWarning" : "green" +} +``` + + + +**Wrap Up** + +Congratulation, if you reached this point of the guide, you managed to create your first aspect model based on BAMM. You can use the presented aspect model as a template for creating your own aspect models. + +If you want to propose or create your own aspect model to be used within Catena-X you can open an issue in [this GitHub repository](https://github.com/eclipse-tractusx/sldt-semantic-models) to get in contact with the modeling community. + + diff --git a/documentation/images/aspect-model.png b/documentation/images/aspect-model.png new file mode 100644 index 00000000..0e5a06a8 Binary files /dev/null and b/documentation/images/aspect-model.png differ diff --git a/documentation/images/bamm-model-2.png b/documentation/images/bamm-model-2.png new file mode 100644 index 00000000..2c86aba2 Binary files /dev/null and b/documentation/images/bamm-model-2.png differ diff --git a/documentation/images/bamm-model.png b/documentation/images/bamm-model.png new file mode 100644 index 00000000..0d289a93 Binary files /dev/null and b/documentation/images/bamm-model.png differ diff --git a/documentation/images/code-messages.png b/documentation/images/code-messages.png new file mode 100644 index 00000000..913c2f94 Binary files /dev/null and b/documentation/images/code-messages.png differ diff --git a/documentation/images/code-snippet-2.png b/documentation/images/code-snippet-2.png new file mode 100644 index 00000000..69f76001 Binary files /dev/null and b/documentation/images/code-snippet-2.png differ diff --git a/documentation/images/code-snippet-3.png b/documentation/images/code-snippet-3.png new file mode 100644 index 00000000..8026f5bf Binary files /dev/null and b/documentation/images/code-snippet-3.png differ diff --git a/documentation/images/code-validation.png b/documentation/images/code-validation.png new file mode 100644 index 00000000..66cd021d Binary files /dev/null and b/documentation/images/code-validation.png differ diff --git a/documentation/images/digital-twin-registry.png b/documentation/images/digital-twin-registry.png new file mode 100644 index 00000000..b496afff Binary files /dev/null and b/documentation/images/digital-twin-registry.png differ diff --git a/documentation/images/dtr-sequence-diagram.png b/documentation/images/dtr-sequence-diagram.png new file mode 100644 index 00000000..d86264f4 Binary files /dev/null and b/documentation/images/dtr-sequence-diagram.png differ diff --git a/documentation/images/example-code-movement.png b/documentation/images/example-code-movement.png new file mode 100644 index 00000000..cb781ba2 Binary files /dev/null and b/documentation/images/example-code-movement.png differ diff --git a/documentation/images/red-yellow-green.png b/documentation/images/red-yellow-green.png new file mode 100644 index 00000000..bb924944 Binary files /dev/null and b/documentation/images/red-yellow-green.png differ diff --git a/documentation/images/ttl-snippet.png b/documentation/images/ttl-snippet.png new file mode 100644 index 00000000..1f40fb36 Binary files /dev/null and b/documentation/images/ttl-snippet.png differ