Aspects

General

Notes

  • As mentioned in the Introduction, Aspect models are described in RDF Turtle [turtle]. The aspect specification will therefore assume basic familiarity with Turtle.

  • For the definition of the different Model elements please refer to the Meta Model Elements.

Naming rules

The naming of Model Elements follows the naming Java naming conventions for classes, properties and methods.

  • The names of Aspects, Entities, Constraints and Characteristics follow the naming conventions for Java classes, i.e. UpperCamelCase.

  • The names of Properties, Operations and Units follow the naming conventions of Java methods, i.e. lowerCamelCase.

RDF/Turtle formatting rules

  • Each Aspect Model is defined in a separate TTL (Turtle) file.

  • The Turtle file containing an Aspect Model must have the same name as the Aspect.

  • Aspect Model files must be UTF-8 encoded and should not contain a byte order mark.

  • There should be one empty line between model element definitions.

  • Indentation should be done with three spaces.

  • There should be a space before every separating semicolon.

  • There should be padding spaces inside RDF lists and anonymous nodes (i.e. inside brackets and square brackets)

Attributes that all model elements have

Every model element (Aspects, Properties, Characteristics, Entities, Operations) has the following attributes:

Attributes Description Required

bamm:name

The name of the property. This name must be defined in Camel Case and be valid a Java Property name (i.e. can not contain spaces, dashes etc.).

bamm:preferredName

Human readable name in a specific language. This attribute may be defined multiple times for different languages but only once for a specific language. There should be at least one preferredName defined with an "en" language tag.

bamm:description

Human readable description in a specific language. This attribute may be defined multiple times for different languages but only once for a specific language. There should be at least one description defined with an "en" language tag.

bamm:see

A reference to a related element in an external taxonomy, ontology or other standards document. The datatype is xsd:anyURI. This attribute may be defined multiple times.

Although both bamm:preferredName and bamm:description should be set at least once in every model element, in the following examples we will mostly leave them out to improve readability.

Declaring model elements

Using Namespaces

An Aspect model file should start with the BAMM prefix definitions. The empty namespace ":" should be used as local namespace, i.e. the versioned namespace in which the Aspect and its elements are defined. Other customer or domain specific namespaces can be defined additionally. However, the bamm-* namespaces are reserved for the meta model. Third party locations can be referred via other namespaces (e.g., "xsd:"). See Namespaces and Versions for more details on the topic.

@prefix : <urn:bamm:com.mycompany.myapplication:1.0.0#> .
@prefix bamm: <urn:bamm:io.openmanufacturing:meta-model:1.0.0#> .
@prefix bamm-c: <urn:bamm:io.openmanufacturing:characteristic:1.0.0#> .
@prefix bamm-e: <urn:bamm:io.openmanufacturing:entity:1.0.0#> .
@prefix unit: <urn:bamm:io.openmanufacturing:unit:1.0.0#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .

Declaring Aspects

An Aspect is defined by marking its identifier with a bamm:Aspect and additional attributes. Note that the a is just a syntactic shortcut for rdf:type. In addition to the general attributes, every Aspect Model element has the following attributes:

Attributes Description Required

bamm:properties

The list of Properties of this Aspect. The attribute must be present, but the list may be empty.

bamm:operations

The list of Operations of this Aspect. The attribute must be present, but the list may be empty.

  • Aspects follow the naming conventions for Java classes, i.e. UpperCamelCase.

  • Each Aspect model must be defined in its own file. The file name must be the same as the Aspect’s name.

  • The name part in the Aspect’s identifying URN must be the same as the Aspect’s bamm:name.

  • The hierarchical namespace part in the Aspect’s URN can be freely chosen.

The definition of an Aspect should therefore have the following structure in TTL syntax; note though that unused namespaces can be left out:

@prefix : <urn:bamm:com.mycompany.myapplication:1.0.0#> .
@prefix bamm: <urn:bamm:io.openmanufacturing:meta-model:1.0.0#> .
@prefix bamm-c: <urn:bamm:io.openmanufacturing:characteristic:1.0.0#> .
@prefix bamm-e: <urn:bamm:io.openmanufacturing:entity:1.0.0#> .
@prefix unit: <urn:bamm:io.openmanufacturing:unit:1.0.0#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .

:MyAspect a bamm:Aspect ;
   bamm:name "MyAspect" ;
   bamm:preferredName "My Aspect"@en ;
   bamm:preferredName "Mein Aspekt"@de ;
   bamm:description "This Aspect is an example."@en ;
   bamm:description "Dieser Aspekt ist ein Beispiel."@de ;
   bamm:properties ( :myProperty :anotherProperty ) ;
   # In this example, there are no operations.
   bamm:operations ( ) .

Declaring Properties

In addition to the attributes that all model elements have, Properties have the following attributes:

Attributes Description Required

bamm:characteristic

The Characteristic describing this Property.

bamm:exampleValue

An exemplary value the Property can take on that helps to understand the intended meaning of the property better. This can only be set for Properties with scalar data types (e.g., xsd:string or xsd:float, but not Entities). The data type of the bamm:exampleValue must be convertible to the effective data type of the Property’s Characteristic. For example, if the Characteristic’s bamm:dataType is xsd:int, xsd:short is also a valid type for the bamm:exampleValue. Refer to section Implicit Conversions for more details.

Example:

:materialNumber a bamm:Property ;
   bamm:name "materialNumber" ;
   bamm:preferredName "Material number"@en ;
   bamm:description "A material number"@en ;
   bamm:exampleValue "ABC123456-000" ;
   bamm:characteristic bamm-c:Text .

Declaring Characteristics

The attributes for Characteristics are described in detail in section Characteristics.

The dataType attribute may be omitted when creating a subclass of a Characteristic. The dataType attribute must be set when creating an instance of a Characteristic, except when the dataType attribute has been set in the class or one of the super-classes. When the dataType has been set in a superclass, the dataType may be set to a subclass of the dataType from one of the Characteristic superclasses. This allows the definition of generic Characteristics such as Collections, where all the semantics are fixed, except for the data type. For a Collection for example it is possible to define whether the collection is sorted or not and this definition can be then reused with different data types to define different collections.

Example:

:MachineState a bamm-c:State ;
   bamm:name "MachineState" ;
   bamm:dataType xsd:string ;
   bamm-c:defaultValue "STANDBY" ;
   bamm-c:values ( "RUNNING" "STANDBY" "OFF" ) .

Declaring Quantifiables and Measurements

Whenever a Property represents a numeric, scalar value that the result of a measurent of some kind (e.g., using a sensor) and has a well-defined physical unit which is known at modeling time, use the Measurement Characteristic. If the value is numeric and has a physical unit but is not the result of a measurement (e.g., when it is calculated from other values), use the Quantifiable Characteristic.

See the following example that uses Measurement — usage of Quantifiable is analogous.

:ToolTemperature a bamm-c:Measurement ;
   bamm:name "ToolTemperature" ;
   bamm:dataType xsd:float ;
   bamm-c:unit unit:degreeCelsius .

:drillHeadTemperature a bamm:Property ;
   bamm:name "drillHeadTemperature" ;
   bamm:characteristic :ToolTemperature .

See section Units for information about the valid values for the bamm-c:unit attribute.

Declaring Single Entity

The following example shows how a Property is defined that uses the Single Entity Characteristic to specify an Entity as its dataType.

:AccelerationVector a bamm:Entity ;
   bamm:name "AccelerationVector" ;
   bamm:properties ( :x :y :z ) .

# Definition of Properties x, y and z for the Entity here
# ...

:acceleration a bamm:Property ;
   bamm:name "acceleration" ;
   bamm:characteristic [
      a bamm-c:SingleEntity ;
      bamm:name "Acceleration" ;
      bamm:dataType :AccelerationVector
   ] .

Declaring Collections

There are four basic predefined types of Collections: Collection, List, Set and Sorted Set. The Collection definitions are shared and are available globally. They determine whether a specific collection is ordered or not and whether a specific collection may contain duplicates or not. In some cases the data type is also set in the shared Collection Characteristic.

These shared Collection Characteristics may not be changed in an Aspect Model, hence it is not allowed to create a subclass of the Collection Characteristic in an Aspect Model. To create a Collection Characteristic for a specific domain, the user should instantiate one of the Collection classes and define the data type or the element Characteristic for the Collection. In this example, the Characteristic resulting from the combination of Code, Length Constraint and Encoding Constraint is not defined inline in the Property, but defined standalone.

Example with a scalar data type:

:NumberList a bamm-c:List ;
   bamm:name "NumberList" ;
   bamm:dataType xsd:float .

Example with a custom Entity as data type:

:MyEntity a bamm:Entity ;
   bamm:name "MyEntity" ;
   bamm:properties ( ) ;
   # ...
   .

:MyEntityList a bamm-c:List ;
   bamm:name "MyEntityList" ;
   bamm:dataType :MyEntity .
The data type for the elements of a Collection can either be defined in the usual manner using the bamm:dataType attribute (see the examples above) or by defining a Characteristic for the Collection elements using the bamm-c:elementCharacteristic attribute, see the example below. It is recommended to explicitly create a Characteristic for the Collection elements instead of only defining the data type, since it allows to completely express the semantics of the elements.

Example with the bamm-c:elementCharacteristic attribute:

:numbers a bamm:Property ;
   bamm:name "numbers" ;
   bamm:characteristic :NumberList .

:NumberList a bamm-c:List ;
   bamm:name "NumberList" ;
   bamm-c:elementCharacteristic [
      a bamm-c:Trait ;
      bamm:name "ElementRange" ;
      bamm-c:baseCharacteristic :Number ;
      bamm-c:constraint [
         a bamm-c:RangeConstraint ;
         bamm:description "Limits the range of the individual numbers in the list from 5 to 10."@en ;
         bamm-c:minValue "5"^^xsd:nonNegativeInteger ;
         bamm-c:maxValue "10"^^xsd:nonNegativeInteger ;
      ] ;
   ] .

:Number a bamm:Characteristic ;
   bamm:name "Number" ;
   bamm:dataType xsd:nonNegativeInteger .

Declaring Enumerations

Describes a Property which may have a value from a predefined list of values. Also see Enumeration.

Example with literal xsd:string values:

:Status a bamm-c:Enumeration ;
   bamm:name "Status" ;
   bamm:dataType xsd:string ;
   bamm-c:values ( "Complete" "In Progress" "Created" ) .

Example with literal xsd:integer values. Note that for xsd:integer, Turtle’s numeric literal syntax can be used:

:PrimesBelowTwenty a bamm-c:Enumeration ;
   bamm:name "PrimesBelowTwenty" ;
   bamm:dataType xsd:integer ;
   bamm-c:values ( 2 3 5 7 11 13 17 19 ) .

Example with literal xsd:int values:

:ValidOffsets a bamm-c:Enumeration ;
   bamm:name "ValidOffsets" ;
   bamm:dataType xsd:int ;
   bamm-c:values ( "-1"^^xsd:int "1"^^xsd:int ) .

Example with literal xsd:date values:

:MaintenanceDates a bamm-c:Enumeration ;
   bamm:name "MaintenanceDates" ;
   bamm:dataType xsd:date ;
   bamm-c:values ( "2010-01-01"^^xsd:date "2012-05-07"^^xsd:date "2018-03-08"^^xsd:date ) .

Example with complex values:

Declaring an Enumeration with a complex value is usally done in order to add a description to the actual value, e.g., the state in the example below, which provides information regarding the meaning of the value. This description only exists in the aspect model and is not part of the payload provided by an Aspect at runtime. In order to define that a Property of an Entity is not part of the runtime data, the bamm:notInPayload attribute is used.

:Results a bamm-c:Enumeration ;
   bamm:name "Results" ;
   bamm:dataType :Result ;
   bamm-c:values ( :Success :Failed ) .

:Result a bamm:Entity ;
   bamm:name "Result" ;
   bamm:properties ( :status [ bamm:property :description; bamm:notInPayload "true"^^xsd:boolean ] ) .

:Success a :Result ;
   :status "SUCCESS" ;
   :description "The process completed successfully." .

:Failed a :Result ;
   :status "FAILURE" ;
   :description "The process did not complete successfully." .
If the Property is part of the runtime data (like status in the example), it is directly referenced. Writing bamm:notInPayload false is not allowed.

Declaring State

As described in State Characteristic, State inherits from Enumeration and extends it with the default value attribute.

Example:

:MachineState a bamm-c:State ;
   bamm:name "MachineState" ;
   bamm:dataType xsd:string ;
   bamm-c:defaultValue "STANDBY" ;
   bamm-c:values ( "RUNNING" "STANDBY" "OFF" ) .

Declaring Time Series

The TimeSeries Characteristic is a special kind of Collection. A Time Series is defined as a list of tuples of values with their respective specific point in time when they where recorded. This is, the Time Series is represented by a list of key/value pairs where the key is the time-stamp denoting when the value was recorded and the value is the recorded value. In order to describe these semantics the shared TimeSeries Characteristic is used. This is a subclass of the SortedSet Characteristic and defines that the dataType must be a subclass of the TimeSeriesEntity.

The TimeSeriesEntity is declared as an Abstract Entity. It defines the timestamp Property with the Timestamp Characteristic, which describes values containing timestamps conforming to xsd:dateTime, a date and time with or without time zone. No value Property is defined, hence the semantics of the value can be defined in the specific Aspect Model.

To create a Time Series for a specific domain, the user should instantiate the TimeSeries Collection Characteristic and set the dataType to an Entity which extends the Abstract TimeSeries Entity in order to define the semantics for the value Property in the context of the specific domain. Please see the Declaring Abstract Entities section for information on how to extend an Abstract Entity.

Example:

:MachineStateTimeSeries a bamm-c:TimeSeries ;
   bamm:name "MachineStateTimeSeries" ;
   bamm:dataType :MachineStateTimeSeriesEntity .

:MachineStateTimeSeriesEntity a bamm:Entity ;
   bamm:name "MachineStateTimeSeriesEntity" ;
   bamm:extends bamm-e:TimeSeriesEntity ;
   bamm:properties ( :machineState ) .

:machineState a bamm:Property ;
   bamm:name "machineState" ;
   bamm:characteristic :MachineState .

:MachineState a bamm-c:State ;
   bamm:name "MachineState" ;
   bamm:dataType xsd:string ;
   bamm-c:defaultValue "STANDBY" ;
   bamm-c:values ( "RUNNING" "STANDBY" "OFF" ) .
An Aspect should only have one Collection at root level. When modeling an Aspect with two or more collections at root level which contain related data, consider creating the model so that the related data is explicitly linked and contained in a single Collection. When modeling an Aspect with two or more collections at root level which contain unrelated data, consider creating separate Aspects each containing a single Collection.

Declaring Either

Describes a Property whose value can have one of two possible types (a disjoint union). This Characteristic is special since it does not directly define a data type. The data type is defined in the two Characteristics which define the left and right value of the disjoint union. Also see Either.

Example:

:Result a bamm-c:Either ;
   bamm:name "Result" ;
   bamm-c:left :ErrorCode ;
   bamm-c:right :SuccessCode .

:ErrorCode a bamm-c:SingleEntity ;
   bamm:name "ErrorCode" ;
   bamm:dataType :ErrorEntity .

:SuccessCode a bamm-c:SingleEntity ;
   bamm:name "SuccessCode" ;
   bamm:dataType :SuccessEntity .

:ErrorEntity a bamm:Entity ;
   bamm:name "ErrorEntity" ;
   bamm:properties ( :errorCode :errorDescription ) .

:SuccessEntity a bamm:Entity ;
   bamm:name "SuccessEntity" ;
   bamm:properties ( :status ) .

Declaring Structured Value

Structured Values are intended to be used for Properties when all of the following conditions are met:

  • The value has a scalar, string-like value space

  • The value has a well-known structure consisting of different, separate parts

  • The parts can and should be described in more detail

  • The Property should not be decomposed/deconstructed into an Entity with separate Properties for each part

One of the main use cases is complex identifiers that encode context information such as provenance information, version numbers, locations codes and so on. It is unreasonable to split such a value up into separate Properties, because it complicates working with corresponding data: For example, such values could appear in payloads, databases or documents and would have to be converted back and forth, often times manually. On the other hand, properly describing the value and the parts it comprises can be difficult, especially in a machine-readable way.

Therefore, the Structured Value Characteristic can be used to describe the deconstruction of a value into its parts and linking each part to a separate Property definition.

The following table gives some simple examples to demonstate the basic applicability of the Characteristic, and after that a complete concrete example is given.

Name Example Value Deconstruction Rule Elements

ISO 8601 date

"2019-09-27"^^xsd:date

(\d{4})-(\d{2})-(\d{2})

( :year "-" :month "-" :day )

Email Address

"user4711@example.com"

([\w\.-]+)@([\w\.-]+\.\w{2,4})

( :username "@" :host )

Hex-encoded color

"0xAC03BE"

0x([0-9A-Fa-f]{2})([0-9A-Fa-f]{2})([0-9A-Fa-f]{2})

( "0x" :red :green :blue )

The following code shows the Aspect model for the first example from the table. Note that when writing the deconstructionRule, backslashes (\) need to be escaped in order to produce valid RDF/Turtle syntax, i.e. write \\ instead of \.

:StructuredValueTest a bamm:Aspect ;
   bamm:name "StructuredValueTest" ;
   bamm:properties ( :date ) ;
   bamm:operations () .

:date a bamm:Property ;
   bamm:name "date" ;
   bamm:exampleValue "2019-09-27"^^xsd:date ;
   bamm:characteristic :StructuredDate .

:StructuredDate a bamm-c:StructuredValue ;
   bamm:name "StructuredDate" ;
   bamm:dataType xsd:date ;
   bamm-c:deconstructionRule "(\\d{4})-(\\d{2})-(\\d{2})" ;
   bamm-c:elements ( :year "-" :month "-" :day ) .

:year a bamm:Property ;
   bamm:name "year" ;
   bamm:characteristic :Year .

:month a bamm:Property ;
   bamm:name "month" ;
   bamm:characteristic :Month .

:day a bamm:Property ;
   bamm:name "day" ;
   bamm:characteristic :Day .

:Year a bamm:Characteristic ;
   bamm:name "Year" ;
   bamm:dataType xsd:int .

:Month a bamm:Characteristic ;
   bamm:name "Month" ;
   bamm:dataType xsd:int .

:Day a bamm:Characteristic ;
   bamm:name "Day" ;
   bamm:dataType xsd:int .
Technically, bamm-c:elements would not be required just to parse corresponding payload; the regular expression given in the bamm-c:deconstructionRule would be sufficient. However, the elements fields serves two purposes: Firstly, it concisely describes how the meaning of the deconstruction rule corresponds with the named fields; secondly, it is used for validation: When a bamm:exampleValue is given (like in the example), the Aspect Model validator can automatically check if it can be deconstructed using the deconstruction rule and reconstructed using the elements, i.e., that the deconstruction rule actually does what the model author intended.

Declaring Constraints and Traits

Consider the numbers Property that uses an instance of the List Characteristic:

:numbers a bamm:Property ;
   bamm:name "numbers" ;
   bamm:characteristic :NumberList .

:NumberList a bamm-c:List ;
   bamm:name "NumberList" ;
   bamm:dataType xsd:integer .

To add a Length Constraint to the list, replace the use of the Characteristic with a new Trait instance. Set the original Characteristic as the Trait’s bamm-c:baseCharacteristic and add the required Constraint as a bamm-c:constraint to the Trait:

:numbers a bamm:Property ;
   bamm:name "numbers" ;
   bamm:characteristic [
     a bamm-c:Trait ;
     bamm:name "LimitedNumberList" ;
     bamm-c:constraint [
       a bamm-c:LengthConstraint ;
       bamm:description "Limits the number list to 10 elements"@en ;
       bamm-c:maxValue "10"^^xsd:nonNegativeInteger ;
       bamm-c:baseCharacteristic :NumberList ;
     ]
   ]  .

:NumberList a bamm-c:List ;
   bamm:name "NumberList" ;
   bamm:dataType xsd:integer .

Another more complex example is given below: The Property someIdentifier is defined that uses a Code instance using a dataType of xsd:string, combined with two Constraints: An Encoding Constraint that restricts the value space to US-ASCII and a Length Constraint that limits the string to 80 characters.

:someIdentifier a bamm:Property ;
   bamm:name "someIdentifier" ;
   bamm:preferredName "Some identifier"@en ;
   bamm:description "An ASCII-encoded identifier with a maximum length of 80 characters"@en ;
   bamm:characteristic :CodeWithLengthAndAscii .

:CodeWithLengthAndAscii a bamm-c:Trait ;
   bamm:name "CodeWithLengthAndAscii" ;
   bamm:description "A string code limited to 80 ASCII characters" ;
   bamm-c:baseCharacteristic [
      a bamm-c:Code ;
      bamm:name "StringCode" ;
      bamm:description "Denotes some kind of code with a string datatype"@en ;
      bamm:dataType xsd:string ;
   ] ;
   bamm-c:constraint [
      a bamm-c:EncodingConstraint ;
      bamm:value bamm:US-ASCII ;
      bamm:description "Limits the character encoding to US-ASCII"@en ;
   ] ;
   bamm-c:constraint [
      a bamm-c:LengthConstraint ;
      bamm:name "CodeWithLength" ;
      bamm:description "Limits the length to 80 characters"@en ;
      bamm-c:maxValue "80"^^xsd:nonNegativeInteger ;
   ] .

An example showing the Regular Expression Constraint is given below:

:timeStampsInJanuary a bamm:Property ;
   bamm:name "timeStampsInJanuary" ;
   bamm:preferredName "Timestamps in January"@en ;
   bamm:description "Contains only timestamps in January of any year"@en ;
   bamm:characteristic [
      a bamm-c:Trait ;
      bamm:name "TimestampInJanuary" ;
      bamm-c:baseCharacteristic bamm-c:Timestamp ;
      bamm-c:constraint [
         a bamm-c:RegularExpressionConstraint ;
         bamm:value "\\d{4}-01-\\d\\dT.*" ;
      ] ;
   ] .
When writing the bamm:value, backslashes (\) need to be escaped in order to produce valid RDF/Turtle syntax, i.e. write \\ instead of \.

Declaring Entities

Entities have the following attributes:

Attributes Description Required

bamm:properties

The list of Properties which make up the Entity

bamm:extends

The Entity which is extended by this Entity

Example:

:Error a bamm:Entity ;
   bamm:name "Error" ;
   bamm:properties ( :errorCode :severity ) .

Extending Entities

Declaring that an Entity extends another Entity is done using the bamm:extends attribute in the Entity declaration.

Example:

:Student a bamm:Entity ;
    bamm:name "Student" ;
    bamm:extends :Person ;
    bamm:properties ( :studentNumber ) .

:Teacher a bamm:Entity ;
    bamm:name "Teacher" ;
    bamm:extends :Person ;
    bamm:properties ( :employeeNumber ) .

:Person a bamm:Entity ;
    bamm:name "Person" ;
    bamm:properties ( :name :surname ) .

The extending Entities :Student and :Teacher contain the Properties declared in the extended Entity :Person as well as the Properties in their own declarations.

The effective Property names, i.e. the payload name when bamm:payloadName is used, or the bamm:name of the Property, must be unique across the entire Entity inheritance chain. Otherwise the corresponding runtime payload is ambiguous.

Declaring Abstract Entities

It is also possible to declare Abstract Entities to share Properties across multiple Entities. An Abstract Entity must be extended by one or more Entities.

Example:

:VehicleComponent a bamm:AbstractEntity ;
    bamm:name "VehicleComponent" ;
    bamm:properties ( :typeNumber :manufacturer ) .

:Steeringwheel a bamm:Entity ;
   bamm:name "Steeringwheel " ;
   bamm:extends :VehicleComponent ;
   bamm:properties ( :isMultifunction  ) .

:Seat a bamm:Entity ;
   bamm:name "Seat" ;
   bamm:extends :VehicleComponent ;
   bamm:properties ( :material )

Declaring Operations

Operations have the following attributes:

Attributes Description Required

bamm:input

A list of references to Properties that describe the input to the operation. The attribute must be present, but the list may be empty.

bamm:output

A single reference to a Property that describes the output of the operation.

Example:

:toggle a bamm:Operation ;
   bamm:name "toggle" ;
   bamm:preferredName "Toggle"@en ;
   bamm:description "Switches the device on or off"@en ;
   bamm:input ( :toggleArgument ) ;
   bamm:output :toggleResult .

:toggleArgument a bamm:Property ;
   bamm:name "toggleArgument" ;
   bamm:preferredName "Toggle argument"@en ;
   bamm:description "The argument for the toggling operation"@en ;
   bamm:characteristic :ToggleValues .

:ToggleValues a bamm-c:Enumeration ;
   bamm:name "ToggleValues" ;
   bamm:preferredName "Toggle values"@en ;
   bamm:description "The possible input values for the toggle operation"@en ;
   bamm:dataType xsd:string ;
   bamm-c:values ( "on" "off" ) .

:toggleResult a bamm:Property ;
   bamm:name "toggleResult" ;
   bamm:preferredName "Toggle result"@en ;
   bamm:description "The result of the toggle operation"@en ;
   bamm:characteristic :ToggleResult .

:ToggleResult a bamm-c:Enumeration ;
   bamm:name "ToggleResult" ;
   bamm:preferredName "Toggle result"@en ;
   bamm:description "The possible results of the toggle operation"@en ;
   bamm:dataType xsd:string ;
   bamm-c:values ( "ok" "denied" "unknown" ) .

Adding external references

The bamm:see attribute can be used to add references to related elements in an external taxonomy, ontology or standards document to Aspect model elements. Values for bamm:see must be URIs. The meaning of the reference is informative and implies no semantics such as equality or subsumption in either direction.

In the following example, bamm:see adds two references to external well-known vocabularies that have identifiers which are also valid URLs:

:lastName a bamm:Property ;
    bamm:name "lastName" ;
    bamm:see <https://schema.org/familyName> ;
    bamm:see <http://xmlns.com/foaf/0.1/lastName> ;
    bamm:characteristic bamm-c:Text .

If an external model element should be referenced that has a unique identifier which is not a URI, but a well-known resolver exists, you can either use the resolver’s URL or a synthetic URN. For example, for the Digital Object Identifier (DOI, [DOI]) 10.1109/NetSys.2017.7903949, you can use as the value for bamm:see either the URL https://doi.org/10.1109/NetSys.2017.7903949 or the URN urn:doi:10.1109/NetSys.2017.7903949.

If an external model element should be referenced that has a unique identifier which is not a URI and there is no well-known resolver, use a synthetic URN structure. One example are Object Identifiers as specified by ITU and ISO/IEC (OID) and the mapping to URNs in RFC 3061 [rfc3061], so for example, for the OID 1.3.6.1.4.1.1919.1.1.2, the corresponding bamm:see value would be urn:oid:1.3.6.1.4.1.1919.1.1.2:

:filterName a bamm:Property ;
    bamm:name "filterName" ;
    bamm:see <urn:oid:1.3.6.1.4.1.1919.1.1.2> ;
    bamm:characteristic bamm-c:Text .

If an external element should be referenced that has no unique identifier, bamm:see should not be used. In this case, refer to the external element in the current model element’s bamm:description, for example:

:organizationPerson a bamm:Property ;
    bamm:name "organizationPerson" ;
    bamm:description "See ISO/IEC 11179-6:2015(E), section 3.35"@en ;
    bamm:characteristic bamm-c:Text .

Optional Properties

When Properties are used in Aspects and Entities, they can be marked as optional. This means that a Property’s usage is optional, not the Property itself, which would make reusing a Property more difficult. In the following example, the Property toggleStatus is mandatory and the Property errorMessage is marked as optional in the Aspect. Note how the bamm:properties of the Aspect are defined, and how the definition for the toggleStatus Property itself does not differ from that of errorMessage.

@prefix : <urn:bamm:com.mycompany.myapplication:1.0.0#> .
@prefix bamm: <urn:bamm:io.openmanufacturing:meta-model:1.0.0#> .
@prefix bamm-c: <urn:bamm:io.openmanufacturing:characteristic:1.0.0#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .

:MyAspect a bamm:Aspect ;
   bamm:name "MyAspect" ;
   bamm:properties (
     :toggleStatus
     [ bamm:property :errorMessage; bamm:optional true ]
   ) ;
   bamm:operations ( ) .

:toggleStatus a bamm:Property ;
   bamm:name "statusNumber" ;
   bamm:characteristic bamm-c:Boolean .

:errorMessage a bamm:Property ;
   bamm:name "errorMessage" ;
   bamm:characteristic bamm-c:Text .
If the Property’s use is optional, it is marked with bamm:optional true (like errorMessage in the example). However, if its use is mandatory (like toggleStatus in the example), the Property is directly referenced. Writing bamm:optional false is not allowed.

Declaring Payload Names for Properties

When Properties are used in Aspects and Entities, a runtime payload name can be defined for the Property. This means that in the context of the Aspect or Entity where the Property is used, the key of that Property in the runtime payload diverges from the Property’s bamm:name. This allows for the separation of the semantic name of the Property and the corresponding key in the runtime payload. In the following example we define a Property errorMessage. In the Aspect it is defined that the corresponding key in the payload is error.

The value for the bamm:payloadName attribute must be of type xsd:string.
@prefix : <urn:bamm:com.mycompany.myapplication:1.0.0#> .
@prefix bamm: <urn:bamm:io.openmanufacturing:meta-model:1.0.0#> .
@prefix bamm-c: <urn:bamm:io.openmanufacturing:characteristic:1.0.0#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .

:MyAspect a bamm:Aspect ;
   bamm:name "MyAspect" ;
   bamm:properties (
     [ bamm:property :errorMessage; bamm:payloadName "error" ]
   ) ;
   bamm:operations ( ) .

:errorMessage a bamm:Property ;
   bamm:name "errorMessage" ;
   bamm:characteristic bamm-c:Text .
A Property may not be marked as not being included in the payload using bamm:notInPayload true and have a payload name declared using bamm:payloadName.

Syntactic Shortcuts

When Properties use Characteristics classes, i.e. Characteristics that need to be instantiated, and the Characteristic instance is used in only one Property, the Characteristic may also be defined inline. Note that other Aspect Models can not refer to the Characteristic any more, because it no longer has an identifier.

Example: Regular definition of a Property

:numbers a bamm:Property ;
   bamm:name "numbers" ;
   bamm:characteristic :NumberList .

:NumberList a bamm-c:List ;
   bamm:name "NumberList" ;
   bamm:dataType xsd:integer .

Example: Inlining the Characteristic definition

:numbers a bamm:Property ;
   bamm:name "numbers" ;
   bamm:characteristic [
      a bamm-c:List;
      bamm:name "NumberList" ;
      bamm:dataType xsd:integer
   ] .