Intermediate Service Model Specification
This page specifies the structure and semantics of the intermediate metamodel for LEMMA service models. All obtained intermediate LEMMA service models must conform to this metamodel to ensure consistent behavior of LEMMA model processors. The following figure shows the metamodel's structure:
The source code of the metamodel specification can be found at https://github.com/SeelabFhdo/lemma/blob/main/de.fhdo.lemma.service.intermediate.metamodel/model/IntermediateServiceModel.xcore.
Each of the following sections describes certain concepts of the metamodel.
Note
Attributes that may contain more than one value but exhibit a *
multiplicity, i.e., they may contain an arbitrary number of values or even
none at all (* is shorthand UML notation for 0..*), are never null.
In case no multiplicity is stated after the object type of an attribute, the
attribute may be null. For example, an attribute defined as String name
implicitly has a multiplicity 0..1 and in the zero-case the String may be
null.
However, in case the attribute's type is a built-in primitive Java type,
e.g. int, the attribute will never be null but exhibits the type's default
value in case it did not receive an explicit value.
Model Root
Class IntermediateServiceModel
Root of an intermediate service model.
String[1] sourceModelUri
file:// URI pointing to the source service model file from which this intermediate service model was derived.
Note
Model processors must not depend on this URI being absolute or relative. Both cases may occur in practice and are up to the modeler.
IntermediateImport[*] imports
References to imported technology models, intermediate domain models, or intermediate service models.
IntermediateMicroservice[1..*] microservices
Microservices defined in the service model.
Microservices
Class IntermediateMicroservice
A modeled microservice.
String[1] sourceModelUri
file:// URI pointing to the source service model file from which this microservice originates.
Note
Model processors must not depend on this URI being absolute or relative. Both cases may occur in practice and are up to the modeler.
String[1] name
Name of the microservice. Unique within the same service model.
String version
Optional version of the service.
String[1] qualifiedName
String[1] type
Type of the microservice. The following values are possible:
| Type | Description |
|---|---|
| "FUNCTIONAL" | A functional microservice realizes the business functions of a microservice architecture. |
| "INFRASTRUCTURE" | Infrastructure microservices provide the architecture with capabilities that are not related to business but technical functions. Examples of such functions comprise database lookups or integration of legacy systems. |
| "UTILITY" | Teams may realize utility microservices to implement reusable, business-related helper functions, e.g., for currency conversion. |
String[1] visibility
Visibility of the microservice. The following values are possible:
| Visibility | Description |
|---|---|
| "INTERNAL" | Service must only be visible to the services of the same team. |
| "ARCHITECTURE" | Service must only be visible to the services of the same architecture, but not to external consumers. |
| "PUBLIC" | Service must be visible to all services of the same architecture and also to external consumers. |
boolean effectivelyImplemented
Flag to indicate if the microservice has at least one operation that is not marked as being not implemented (either directly or transitively via its defining interface.
Hint
Model processors should consider to also handle not (yet) implemented microservices. Code generators, for example, might produce code that returns failures upon invocation of non-implemented service capabilities.
IntermediateTechnology[*] technologies
Technologies assigned to the microservice.
Hint
There can only be one technology that defines default primitive types. Moreover, it is guaranteed that default protocol/data format combinations are unambiguous. For instance, there can only be one default synchronous protocol across all referenced technologies.
Note
In case no fitting technologies are specified for a microservice, model processors are free to omit processing steps if they cover only specific technologies.
IntermediateEndpoint[*] endpoints
Endpoints specified for the microservice.
Hint
If no endpoints were modeled for the microservice's (default) protocol specifications , the addresses attribute of the IntermediateEndpoint instance will be empty.
Hint
If no endpoints were specified or could be determined from (default) protocol specifications , or in case the addresses attribute is empty, model processors may assume sensible defaults.
IntermediateProtocolSpecification[0..2] protocols
Protocol specifications of the microservice. There might be at most one protocol specification per communication type (synchronous or asynchronous).
Hint
If the service has no protocol specifications, code generators may produce sensible defaults, e.g., from the microservice's name.
Note
In case the microservice had no protocols assigned in the source service model, the default protocols of the missing communication types are taken from the service's technologies, if any. That is, the attribute will only be empty if the microservice had no protocol-defining technology assigned.
MicroserviceReference[*] requiredMicroservices
References to required microservices.
InterfaceReference[*] requiredInterfaces
References to required interfaces.
OperationReference[*] requiredOperations
References to required operations.
IntermediateImportedAspect[*] aspects
Aspects of the microservice.
IntermediateServiceModel serviceModel
Link to the defining IntermediateServiceModel instance.
Class IntermediateInterface
This class represents an interface of an IntermediateMicroservice.
String[1] name
Name of the interface. Unique within the same microservice.
String version
Optional version of the interface.
String[1] qualifiedName
Qualified name of the interface. Consists of the defining microservice's qualified name, and the interface's version and name. All name fragments are separated by dots.
String[1] visibility
Visibility of the interface. The following values are possible:
| Visibility | Description |
|---|---|
| "INTERNAL" | Interface must only be visible to the services of the same team. |
| "IN_MODEL" | Interface must only be visible to the services within the same service model file. |
| "ARCHITECTURE" | Interface must only be visible to the services of the same architecture, but not to external consumers. |
| "PUBLIC" | Interface must be visible to all services of the same architecture and also to external consumers. |
boolean notImplemented
Flag to indicate if the interface was marked as being not implemented.
Hint
Model processors should consider to also handle not (yet) implemented interfaces. Code generators, for example, might produce code that returns failures upon invocation of non-implemented service capabilities.
boolean hasImplementedOperations
Flag to indicate if the interface has at least one operation that is not marked as being not implemented.
Hint
Model processors should consider to also handle not (yet) implemented interfaces. Code generators, for example, might produce code that returns failures upon invocation of non-implemented service capabilities.
Note
The notImplemented and hasImplementedOperations flags are independent of each other. The former is set by the modeler, while the latter is derived from the corresponding flags of the interface's operations.
IntermediateEndpoint[*] endpoints
Endpoints specified for the interface.
Hint
If no endpoints were modeled for the interface's (default) protocol specifications , the addresses attribute of the IntermediateEndpoint instance will be empty.
Hint
If no endpoints were specified or could be determined from (default) protocol specifications , or in case the addresses attribute is empty, model processors may assume sensible defaults.
IntermediateProtocolSpecification[0..2] protocols
Protocol specifications of the interface. There might be at most one protocol specification per communication type (synchronous or asynchronous).
Hint
If no protocols were explicitly specified for the interface, it "inherits" the specifications of its microservice. In case the service does also not exhibit protocol specifications, model processors should assume sensible defaults.
Note
In case the microservice had no protocols assigned in the source service model, the default protocols of the missing communication types are taken from the service's technologies, if any. That is, the attribute will only be empty if the microservice had no protocol-defining technology assigned.
IntermediateOperation[*] operations
Operations of the interface.
IntermediateReferredOperation[*] referredOperations
Referred operations of the interface.
Note
An interface defines at least one operation or refers to an existing operation, i.e., at least one of the attributes operations and [referredOperations] is not empty.
IntermediateImportedAspectconcept-[*] aspects
Aspects of the interface.
IntermediateMicroservice microservice
Link to the defining IntermediateMicroservice instance.
Class IntermediateOperation
This class represents an operation of an IntermediateInterface.
String[1] name
Name of the operation. Unique within the same interface.
String[1] qualifiedName
Qualified name of the operation. Consists of the operation's name prefixed by its interface's qualified name. Both name fragments are separated by dots.
String[1] visibility
Visibility of the microservice. The following values are possible:
| Visibility | Description |
|---|---|
| "INTERNAL" | Operation must only be visible to the services of the same team. |
| "IN_MODEL" | Operation must only be visible to the services within the same service model file. |
| "ARCHITECTURE" | Operation must only be visible to the services of the same architecture, but not to external consumers. |
| "PUBLIC" | Operation must be visible to all services of the same architecture and also to external consumers. |
boolean notImplemented
Flag to indicate if the operation was marked as being not implemented.
Hint
Model processors should consider to also handle not (yet) implemented operations. Code generators, for example, might produce code that returns failures upon invocation of non-implemented service capabilities.
IntermediateEndpoint[*] endpoints
Endpoints specified for the interface.
Hint
If no endpoints were modeled for the operation's (default) protocol specifications , the addresses attribute of the IntermediateEndpoint instance will be empty.
Hint
If no endpoints were specified or could be determined from (default) protocol specifications , or in case the addresses attribute is empty, model processors may assume sensible defaults.
IntermediateProtocolSpecification[0..2] protocols
Protocol specifications of the operation. There might be at most one protocol specification per communication type (synchronous or asynchronous).
Hint
If no protocols were explicitly specified for the operation, it "inherits" the specifications of its interface. In case the interface does also not exhibit protocol specifications, model processors should assume sensible defaults.
IntermediateParameter[*] parameters
The operation's parameters.
Hint
There might be more than one outgoing parameter and it is up to model processors on how to interpret such circumstances. For example, a code generator might represent all outgoing parameters as fields of a uniforming data structure.
IntermediateApiOperationComment[0..1] apiOperationComment
API comment of the operation.
IntermediateImportedAspect[*] aspects
Aspects of the operation.
IntermediateInterface interface
Link to the defining IntermediateInterface instance.
Class IntermediateApiOperationComment
This concept represents an API-related comment of a microservice operation. Such comments shall describe the purpose of a microservice operation, possibly including its parameters (cf. the IntermediateApiParameterComment concept).
String[1] comment
Comment content.
IntermediateApiParameterComment[*] parameterComments
API comments for the operation's parameters.
Hint
It is possible that a parameter is commented more than once. It is up to model processors how they treat such a situation. For instance, a code generator might ignore all comments except for the last one.
IntermediateOperation operation
The operation documented by this comment.
Class IntermediateApiParameterComment
This concept represents an API-related comment of a microservice operation parameter.
String[1] comment
Comment content.
boolean required
Flag to indicate if this parameter is required by the described API.
Note
It is possible to even document parameters that were modeled optional as required.
boolean returned
Flag to indicate if this parameter is returned by the described API.
IntermediateParameter parameter
The parameter documented by this comment.
IntermediateApiOperationComment operationComment
The API operation comment to which this parameter comment belongs.
Class IntermediateParameter
A microservice operation parameter.
String[1] name
Name of the parameter. Unique within the same operation.
String[1] qualifiedName
Qualified name of the parameter. Consists of the parameter's name prefixed by its operation's qualified name. Both name fragments are separated by dots.
String[1] exchangePattern
Exchange pattern of the parameter. The following values are possible:
| Pattern | Description |
|---|---|
| "IN" | Incoming information exchange. |
| "OUT" | Outgoing information exchange. |
| "INOUT" | Incoming and outgoing information exchange. |
String[1] communicationType
Communication type of the parameter. The following values are possible:
| Type | Description |
|---|---|
| "ASYNCHRONOUS" | Asynchronous communication. |
| "SYNCHRONOUS" | Synchronous communication. |
boolean communicatesFault
Flag to indicate that the parameter communicates failure values to the caller.
Note
If necessary, it is up to model processors to ensure that callers are aware of the parameter communicating failure values.
boolean optional
Flag to indicate that the parameter is optional.
Note
The combination of exchange pattern, communication type, and the optional attribute determines a parameter's and thus operation's "timing behavior":
| Exchange Pattern | Communication Type | Optional? | Timing Behavior |
|---|---|---|---|
| "IN" | "ASYNCHRONOUS" | false |
Operation must receive value at some point in time during its execution for the respective parameter. |
| "IN" | "ASYNCHRONOUS" | true |
Operation may receive value at some point in time during its execution for the respective parameter. |
| "IN" | "SYNCHRONOUS" | false |
Operation is only executable with the respective parameter receiving a value. |
| "IN" | "SYNCHRONOUS" | true |
Operation is executable without the respective parameter receiving a value. Furthermore, the operation cannot expect to ever receive a value for the respective parameter. |
| "OUT" | "ASYNCHRONOUS" | false |
Operation uses the respective parameter to emit a value at some point in time during its execution. |
| "OUT" | "ASYNCHRONOUS" | true |
Operation may use the respective parameter to emit a value at some point in time during its execution. |
| "OUT" | "SYNCHRONOUS" | false |
Operation uses the respective parameter to emit a value after its execution. |
| "OUT" | "SYNCHRONOUS" | true |
Operation may use the respective parameter to emit a value after its execution. |
| "INOUT" | all | all |
Operation treats the parameter as an
incoming and outgoing parameter for
the concrete communication type and
optional flag.
|
IntermediateType[1] type
The type of the parameter.
Hint
Model processors must use this type as the parameter's type and not the originalType.
Note
A parameter can receive the unspecified type only if the operation is not implemented.
IntermediateType[1] originalType
The original type of the parameter.
Hint
The attribute always holds a value. In case the value differs from that of the type attribute, the parameter type got altered in a mapping model and the type attribute attribute holds an instance of the IntermediateImportedTechnologySpecificType concept that identifies the technology-specific type to which the original return type was mapped.
OperationReference initializedByOperation
Link to the IntermediateOperation that initializes the parameter.
Note
It is not guaranteed that the operation's return values and the parameter's type are compatible. This is due to LEMMA's Service Modeling Language yielding a warning only in case it detected a (possible) type incompatibility.
IntermediateImportedAspect[*] aspects
Aspects of the parameter.
DataFieldAspects[*] fieldAspects
Aspects that were assigned to fields of the structure type or enumeration type of the parameter within a mapping model.
Hint
These aspects are relevant only in the context of the parameter within its defining operation. That is, they are not relevant in the context of the type that defines the fields within its domain model.
IntermediateOperation operation
Link to the defining IntermediateOperation instance.
Class DataFieldAspects
This concept gathers aspects, which were assigned to fields of a parameter's structure type or enumeration type within a mapping model.
String[1] name
The name of the structure type's or enumeration type's field to which the aspects were assigned in the context of the parameter.
String[1] qualifiedName
Qualified name of the field. Consists of the field's name prefixed by the parameter's qualified name. Both name fragments are separated by dots.
IntermediateImportedAspect[1..*] aspects
The aspects that were assigned to the field in the context of the parameter.
IntermediateParameter parameter
Link to the defining IntermediateParameter instance.
Class IntermediateReferredOperation
Referred operation of an interface. By contrast to "locally defined" operations, referred operations do not implement their own business logic. Instead, they act as façades to implemented operations within the same microservice. That is, requests/responses to the original operation/the caller are just forwarded by referred operations.
Referred operations exhibit the same parameters as the original operations. However, they may have different endpoints, protocols, and aspects.
String[1] nameInReferringInterface
The name of the referred operation within the referring interface. Currently, this name is identical to the name of the original operation. However, model processors should not rely on that fact and instead use the content of this attribute to process the referring operation.
String[1] qualifiedNameInReferringInterface
The qualified name of the referred operation within the referring interface. It consists of the name of the referring operation prefixed by the defining interface's qualified name. Both name fragments are separated by dots.
IntermediateOperation[1] operation
Link to the original operation.
Note
The type of the attribute is IntermediateOperation instead of OperationReference because the original operation must reside in the same microservice as the referring operation and can thus not originate from an imported service model.
IntermediateEndpoint[*] endpoints
Endpoints specified for the referred operation.
Hint
If no endpoints were modeled for the referred operation's (default) protocol specifications , the addresses attribute of the IntermediateEndpoint instance will be empty.
Hint
If no endpoints were specified or could be determined from (default) protocol specifications , or in case the addresses attribute is empty, model processors may assume sensible defaults.
IntermediateProtocolSpecification[0..2] protocols
Protocol specifications of the referred operation. There might be at most one protocol specification per communication type (synchronous or asynchronous).
Hint
If no protocols were explicitly specified for the referred operation, it "inherits" the specifications of its interface. In case the interface does also not exhibit protocol specifications, model processors should assume sensible defaults.
IntermediateImportedAspect[*] aspects
Aspects of the referred operation.
IntermediateInterface referringInterface
Link to the IntermediateInterface instance, which refers to the operation.
Communication
This subsection describes concepts for the specification of microservice communication.
Class IntermediateEndpoint
A protocol- and format-specific endpoint, e.g., "http://example.org" for the HTTP protocol and "application/json" for the JSON data format.
String[1] communicationType
Communication type of the endpoint. Corresponds to the type of the endpoint's protocol. The following values are possible:
| Type | Description |
|---|---|
| "ASYNCHRONOUS" | Asynchronous communication. |
| "SYNCHRONOUS" | Synchronous communication. |
String[1] protocol
Name of the endpoint's protocol.
String[1] dataFormat
Name of the endpoint's data format. LEMMA does not prescribe the notation of data formats in defining technology models. For instance, model processors may refer to the JSON format by means of its simple name, e.g., "json", or its MIME type, i.e., "application/json". Hence, it is in the responsibility of model processor developers to ensure that processors are compatible with technology models.
String[*] addresses
List of protocol- and format-specific addresses that were assigned to the endpoint, e.g., "http://example.org".
Hint
If the list of addresses is empty, model processors should assume sensible defaults as described for microservices, interfaces, operations, and referred operations.
Hint
In case the modeler did not specify a data format for an endpoint, it depends on the technology model, which endpoints are created in the intermediate service model:
- If the technology model defines a default protocol and thus a default format, an endpoint for this protocol and format is created in the intermediate service model.
- If the protocol is not the default protocol for the communication type and hence does not define a default format, endpoints for all formats supported by the protocol are created.
Hint
The addresses are not checked for validity by the Service Modeling Language. Model processors are required to perform validation, if necessary.
IntermediateTechnology[1] technology
Link to the technology model, which defines the protocol and data format.
IntermediateMicroservice microservice
Microservice for which the endpoint was specified.
IntermediateInterface interface
Interface for which the endpoint was specified.
IntermediateOperation operation
Operation for which the endpoint was specified.
IntermediateReferredOperation referredOperation
Referred operation for which the endpoint was specified.
Class IntermediateProtocolSpecification
A protocol and data format specification.
String[1] communicationType
Communication type of the specification. The following values are possible:
| Type | Description |
|---|---|
| "ASYNCHRONOUS" | Asynchronous communication. |
| "SYNCHRONOUS" | Synchronous communication. |
String[1] protocol
Name of the specification's protocol.
String[1] dataFormat
Name of the specification's data format.
Technologies
Class IntermediateTechnology
Intermediate representation of a technology that originates from an imported technology model and has been applied to a microservice.
String[1] name
The technology's name.
IntermediateImport[1] import
Intermediate representation of the technology model's import.
IntermediateMicroservice[1] microservice
Intermediate representation of the microservice to which the technology has been applied.
References
This subsection describes concepts that model references to possibly imported microservices, interfaces, or operations.
Class MicroserviceReference
Reference to a possibly imported microservice.
String[1] name
Name of the referenced microservice.
String version
Version of the referenced microservice.
String[1] qualifiedName
Qualified name of the referenced microservice.
boolean imported
Flag to indicate if the referenced microservice was imported from another service model.
IntermediateImport import
The import, which points to the imported service model from which the referenced microservice originates. Iff the imported flag flag is true, this attribute also contains a value.
IntermediateMicroservice localMicroservice
Link to the referenced microservice in the same service model as the MicroserviceReference. Iff the imported flag flag is false, this attribute also contains a value.
Hint
If the attribute is null, i.e., the referenced microservice is defined in another, imported service model, model processors need to retrieve details about the referenced service from the imported service model themselves. That is, they need to parse the imported model and find the referenced microservice leveraging the qualifiedName attribute of the MicroserviceReference instance.
IntermediateMicroservice requiringMicroservice
Link to the microservice that requires the referenced microservice.
Class InterfaceReference
Reference to a possibly imported interface.
String[1] name
Name of the referenced interface.
String version
Version of the referenced interface.
String[1] qualifiedName
Qualified name of the referenced interface.
boolean imported
Flag to indicate if the referenced interface was imported from another service model.
IntermediateImport import
The import, which points to the imported service model from which the referenced interface originates. Iff the the imported flag flag is true, this attribute also contains a value.
IntermediateInterface localInterface
Link to the referenced interface in the same service model as the InterfaceReference. Iff the imported flag flag is false, this attribute also contains a value.
Hint
If the attribute is null, i.e., the referenced interface is defined in another, imported service model, model processors need to retrieve details about the referenced interface from the imported service model themselves. That is, they need to parse the imported model and find the referenced interface leveraging the qualifiedName attribute of the InterfaceReference instance.
IntermediateMicroservice requiringMicroservice
Link to the microservice that requires the referenced interface.
Class OperationReference
Reference to a possibly imported operation.
String[1] name
Name of the referenced operation.
String[1] qualifiedName
Qualified name of the referenced operation.
boolean imported
Flag to indicate if the referenced operation was imported from another service model.
IntermediateImport import
The import, which points to the imported service model from which the referenced operation originates. Iff the the imported flag flag is true, this attribute also contains a value.
IntermediateOperation localOperation
Link to the referenced operation in the same service model as the OperationReference. Iff the imported flag flag is false, this attribute also contains a value.
Hint
If the attribute is null, i.e., the referenced operation is defined in another, imported service model, model processors need to retrieve details about the referenced operation from the imported service model themselves. That is, they need to parse the imported model and find the referenced operation leveraging the qualifiedName attribute of the OperationReference instance.
IntermediateMicroservice requiringMicroservice
Link to the microservice that requires the referenced operation.
IntermediateParameter initializedParameter
Link to the parameter that is initialized by the referenced operation.