Public release MDSL V5.3.3

Author: socadk

README.md

@@ -1,4 +1,4 @@
-Microservice Domain-Specific Language (MDSL) 5.2
+Microservice Domain-Specific Language (MDSL) 5.3
 ================================================
 
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
@@ -41,7 +41,7 @@ These two languages can be used independently of each other; for instance, data
 
 ## Getting Started
 
-* The [GitHub Pages for MDSL](https://microservice-api-patterns.github.io/MDSL-Specification) provide a tutorial and language reference information.<!-- * There is a [Project Wiki](https://github.com/Microservice-API-Patterns/MDSL-Specification/wiki/Getting-Started-with-MDSL), which is not populated much (yet) and not kept up to date as much as the GitHub pages. -->
+* The public [GitHub Pages for MDSL](https://microservice-api-patterns.github.io/MDSL-Specification/) provide a tutorial and language reference information.
 * There is an [Eclipse update site](https://microservice-api-patterns.github.io/MDSL-Specification/updates/) for the MDSL editor. 
 * All generators are available via a Command Line Interface (CLI); see [this readme](./dsl-core/io.mdsl.cli/README.md) and [these examples](./examples/mdsl-standalone-example).
 * Presentations featuring Context Mapper, MAP and MDSL can be found [here](https://ozimmer.ch/papers/), and an [end-to-end demo](https://medium.com/olzzio/domain-driven-service-design-with-context-mapper-and-mdsl-d5a0fc6091c2) is available on Medium.
@@ -50,7 +50,7 @@ These two languages can be used independently of each other; for instance, data
 
 ## Language Specification 
 
-* [Overview](https://microservice-api-patterns.github.io/MDSL-Specification)
+* [Primer](https://microservice-api-patterns.github.io/MDSL-Specification/primer)
 * [Endpoint types](https://microservice-api-patterns.github.io/MDSL-Specification/servicecontract) (a.k.a. ports)
 * [Bindings](https://microservice-api-patterns.github.io/MDSL-Specification/bindings) (a.k.a. adapters)
 * [Data types](https://microservice-api-patterns.github.io/MDSL-Specification/datacontract) (a.k.a. published language)
@@ -76,7 +76,9 @@ If you want to contribute to MDSL, you have to clone this repo and generate the
 
 ## Change Log
 
-The current version of the MDSL language is 5.2; the tool version is 5.2.2. This MDSL version extends service contracts with support for events, states, flows, compensation (as experimental technology previews). It also supports true REST level 3 concepts both on the abstract endpoint type level and in the redesigned bindings and comes with additional Fremarker generators (Markdown reports, ALPS).
+The latest version of the MDSL language MDSL version extends service contracts with support for events, states, compensation as well as integration scenarios as stories(as experimental technology previews). These concepts are featured in a number of model transformations that support rapid "API First" development.
+
+Since Version 5.2, MDSL supports true REST level 3 concepts both on the abstract endpoint type level and in the redesigned bindings and comes with additional Freemarker generators (Markdown reports, ALPS).
 
 See [change log](changelog.md) for an evolution history; see GitHub [release notes](https://github.com/Microservice-API-Patterns/MDSL-Specification/releases) for additional update information.
 

background/readme.md

@@ -27,7 +27,7 @@ This folder contains pointers to background information such as related projects
 ## MDSL and Context Mapper 
 
 * Zimmermann, O.: Dimensions of Successful Web API Design and Evolution: Context, Contracts, Components, Keynote, 20th International Conference on Web Engineering (ICWE), June 11, 2020. ([PDF](https://ozimmer.ch/assets/presos/ZIO-ICWEKeynoteWADEC3v10p.pdf), [blog post](https://ozimmer.ch/practices/2020/06/10/ICWEKeynoteAndDemo.html))
-* Kapferer, S.; Zimmermann, O.: Domain-driven Service Design — Context Modeling, Model Refactoring and Contract Generation. Proc. of SummerSoC 2020 conference, Springer CCIS Volume 1310 ([PDF](https://contextmapper.org/media/SummerSoC-2020_Domain-driven-Service-Design_Authors-Copy.pdf), [Presentation]())
+* Kapferer, S.; Zimmermann, O.: Domain-driven Service Design — Context Modeling, Model Refactoring and Contract Generation. Proc. of SummerSoC 2020 conference, Springer CCIS Volume 1310 ([PDF](https://contextmapper.org/media/SummerSoC-2020_Domain-driven-Service-Design_Authors-Copy.pdf), [Presentation](https://contextmapper.org/media/Stefan-Kapferer_SummerSoC2020_presentation.pdf))
 
 <!-- plus VSS Vienna conference report by Leitner et al (Insights) -->
 

changelog.md

@@ -1,6 +1,21 @@
 ## MDSL change log (and release notes)
 
-Also see GitHub [release notes](https://github.com/Microservice-API-Patterns/MDSL-Specification/releases).
+V5.3
+
+* Additional features and consistency cleanup in orchestration flow and story/scenario grammar
+* Corresponding tool support in 20+ quick fix transformations
+* Selected transformations also available in standalone API and CLI
+
+V5.2.9, June 2021
+
+* API client no longer needs an HTTP resource binding
+* `content` keyword removed from event types and command types 
+* HTP binding validation disabled in gateway `Gate`s 
+* Many quick fixes to support rapid SOAD and API refactoring to MAP
+* Demo of two menu-level refactorings: Move Operation/Extract Endpoint and Add MAP Decorator
+
+* Grammar makes endpoint type optional
+* Type system can be `OTHER` or `AnyCustomString`
 
 V5.2, June 2021
 
@@ -158,4 +173,6 @@ V0.93a, May 10, 2019:
 V0.93b, May 10, 2019 (experimental):
 
 * Only `V<int>` supported as parameter role/type pair, `Value<int>` removed to avoid confusion with `<<stereotypes>>`
-* `<<Identifier>>` and `<<Link>>` and `<<Metadata>>` now available as pattern stereotypes (`<<Entity>>` was supported already)
+* `<<Identifier>>` and `<<Link>>` and `<<Metadata>>` now available as pattern stereotypes (`<<Entity>>` was supported already)
+
+Also see GitHub [release notes](https://github.com/Microservice-API-Patterns/MDSL-Specification/releases).

docs/HelloWorldWebsitePrimer.graphql

@@ -0,0 +1,33 @@
+# GraphQL generated for endpoint HelloWorldEndpoint of HelloWorldAPI
+
+
+input SampleDTOInput {
+	anonymous1: VoidResponse!
+	anonymous2: String!
+}
+input sayHelloRequestDataTypeInput {
+	in: String!
+}
+type SampleDTOOutput {
+	anonymous1: VoidResponse!
+	anonymous2: String!
+}
+type sayHelloRequestDataTypeOutput {
+	in: String!
+}
+
+
+type Mutation {
+	sayHello(
+		in: sayHelloRequestDataTypeInput
+	): SampleDTOOutput
+}
+
+schema {
+	
+	mutation: Mutation
+}
+
+# additional scalars for types in MDSL
+scalar Raw
+scalar VoidResponse

docs/HelloWorldWebsitePrimer.proto

@@ -0,0 +1,19 @@
+syntax = "proto3";
+
+package HelloWorldAPI;
+
+import "google/protobuf/any.proto";
+
+message SampleDTO {
+  google.protobuf.Any anonymous1 = 1;
+  string anonymous2 = 2;
+}
+
+message sayHelloRequestMessage {
+  string in = 1;
+}
+
+service HelloWorldEndpoint {
+  rpc sayHello(sayHelloRequestMessage) returns (SampleDTO);
+}
+

docs/HelloWorldWebsitePrimer.yaml

@@ -0,0 +1,45 @@
+openapi: 3.0.1
+info:
+  title: HelloWorldAPI
+  version: "1.0"
+servers:
+- url: http://localhost:8000
+tags:
+- name: HelloWorldAPIProvider-HomeResource
+  externalDocs:
+    description: The role of this endpoint, offering a HelloWorldEndpoint contract,
+      is not specified.
+    url: ""
+paths:
+  /:
+    post:
+      tags:
+      - HelloWorldAPIProvider-HomeResource
+      description: unspecified operation responsibility
+      operationId: HomeResource-sayHello
+      parameters: []
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                in:
+                  type: string
+      responses:
+        "200":
+          description: sayHello successful execution
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/SampleDTO'
+components:
+  schemas:
+    SampleDTO:
+      type: object
+      properties:
+        anonymous1:
+          type: string
+          format: uuid
+        anonymous2:
+          type: string

docs/HelloWorldWebsitePrimerGeneratedIDLs.zip

@@ -66,9 +66,7 @@ The role stereotypes can be combined with the following base types to yield prec
 
 #### Complex Types
 
-See explanations above (under "simple, yet powerful nesting is supported"). 
-
-<!-- TODO (M): the "quick reference" cheat sheet that used to be in grammar/examples in V2 would fit here -->
+See explanations above (under "simple, yet powerful nesting is supported"), as well as [Quick Reference](./quickreference).
 
 ### Collections and optionality 
 
@@ -81,21 +79,21 @@ Parameter trees and atomic parameter lists can be used to express optionality if
 ~~~
 DataContract:
     'data' 'type' name=ID 
-    ('version' svi=semanticVersioningIdentifier)? 
-    structure=elementStructure;
-    default=defaultValue?
+    ('version' svi=SemanticVersioningIdentifier)? 
+    structure=ElementStructure;
+    default=DefaultValue?
 
 ElementStructure: 
-    pf=parameterForest | pt=parameterTree 
-  | apl=atomicParameterList  | np=singleParameterNode;
+    pf=ParameterForest | pt=ParameterTree 
+  | apl=AtomicParameterList | np=SingleParameterNode;
 
 [...]
 
 TreeNode:
-    spn=singleParameterNode | apl=atomicParameterList | pt=parameterTree;
+    spn=SingleParameterNode | apl=AtomicParameterList | pt=ParameterTree;
 
 SingleParameterNode: 
-    genP=genericParameter | atomP=atomicParameter | tr=typeReference;
+    genP=GenericParameter | atomP=AtomicParameter | tr=TypeReference;
 ~~~
 
 The semantic versioning identifier `svi` is a simple `STRING`; at present, the entire API as well as data types, endpoints and operations can be versioned. 
@@ -152,11 +150,11 @@ data type CustomerWithAddressAndMoveHistory {
 
 Note that a parameter tree that only contains atomic parameters `{D<int>, D<string>}` can also be modeled as an Atomic Parameter List `(D<int>, D<string>)`. It is recommended to prefer the Parameter Tree syntax over that of the Atomic Parameter List (to promote information hiding and defer detailed modeling decisions until the last/most responsible moment). `<<Entity>>` is a patttern stereotype (see section "Outlook: MAP Decorators" of the [CSV tutorial](./tutorial) for explanations).
 
-<!-- TODO (H): * feature choice '|' -->
+<!-- TODO (H): * feature choice '|' when supported in all tools -->
 
 <!-- TODO feature CSV in new Tutorial "sheets": ["rows":{"columnCells":{Data|Formula}*}*] // title row is different? -->
 
-<!-- TODO model this in JSON Schema and XML Schema (and/or Avro?) -->
+<!-- TODO model this in JSON Schema, XML Schema (and/or Avro?) -->
 
 
 ## Technology Mappings

docs/datacontract.md

@@ -6,6 +6,7 @@ copyright: Olaf Zimmermann, 2019. All rights reserved.
 
 [Home](./index) — [Endpoint Type](./servicecontract) — [Data Type](./datacontract) — [Provider and Client](./optionalparts) — [Bindings](./bindings) — [Cheat Sheet](./quickreference) — [Tools](./tools)
 
+<!-- TODO (H) update for 5.3 and merge/align with primer? -->
 
 MDSL Examples
 =============
@@ -75,23 +76,23 @@ data type SomeFlatRecord (D<string>, D<int>, D<bool>)
 data type ChoiceDemo {"optionA":D | "optionB":D} // not implemented in tools yet
 ~~~
 
-## More Examples 
+More examples can be found in in the [public](https://github.com/Microservice-API-Patterns/MDSL-Specification/tree/master/examples) <!-- and in the [private](https://github.com/Microservice-API-Patterns/MDSL-Specification/tree/master/examples) --> MDSL repository.
 
-Can be found in the repo. 
-
-<!-- TODO feture RESTBucks here -->
+<!-- TODO (M) feature RESTBucks here -->
 
 ## Links
 
-[Quick reference skeletons](./quickreference). 
-
-More on service [endpoint contract types](./servicecontract) and [data contracts (schemas)](./datacontract). 
-
-Optional [Instance-level language constructs](./optionalparts).
-
-Back to [MDSL homepage](./index). 
 
-More examples in [public](https://github.com/Microservice-API-Patterns/MDSL-Specification/tree/master/examples) and in [private](https://github.com/Microservice-API-Patterns/MDSL-Specification/tree/master/examples) repository.
+* API usage [scenarios and stories](scenarios.md) (experimental)
+* Orchestration [flows](flows.md) (experimental)
+* Service [endpoint contract types](./servicecontract)
+* [Data contracts (schemas)](./datacontract)
+* [Bindings](./bindings)
+* Optional [language elements on the instance level (provider, client, gateway)](./optionalparts)
+* [Tutorial](./tutorial), another [example](./examples)
+* [Quick reference](./quickreference)
+* [Tool information (CLI, editor/linter)](./tools)
+* [SOAD transformations](./soad)
 
 *Copyright: Olaf Zimmermann, 2018-2021. All rights reserved. See [license information](https://github.com/Microservice-API-Patterns/MDSL-Specification/blob/master/LICENSE).*
 

docs/examples.md

@@ -0,0 +1,120 @@
+---
+title: Microservice Domain Specific Language (MDSL) Orchestration Flows
+author: Olaf Zimmermann
+copyright: Olaf Zimmermann, 2021.  All rights reserved.
+---
+
+[Home](./index) — [Data Types](./datacontract) — [Bindings](./bindings) — [Provider and Client](./optionalparts) — [Tutorial](./tutorial) — [Cheat Sheet](./quickreference) — [Tools](./tools)
+
+Orchestration Flows
+===================
+
+_Note:_ The status of these language concept is [*Experimental Preview*](https://microservice-api-patterns.org/patterns/evolution/ExperimentalPreview.html). The grammar and the tool support might change, in breaking ways, in future versions of MDSL.
+
+## Use Cases (When to Specify)
+
+* Rapid prototyping (for instance, of event storming results coming in from [Context Mapper](https://contextmapper.org/docs/application-and-process-layer/))
+* API call sequencing 
+* Integration flows, as input for middleware such as Apache Camel 
+
+<!-- 
+* Early SOAD
+* Application flows in inside a service
+* Service orchestration, API operation call sequencing
+* EIP-style integration flows (asynch., pipes and filters)
+* Testing (mocking, staging)
+-->
+
+## Grammar Excerpts 
+
+This is an optional language concept. The flow grammar is subject to change as this is a technology preview.
+
+### Flow and flow steps (with technology binding)
+
+~~~
+Orchestration:
+	'flow' name=ID 
+	  ('realizes' scenario=[IntegrationScenario])? ('type' type=FlowType)? 
+	steps+=FlowStep* 
+	flowBinding=OrchestrationBinding?
+;
+~~~
+
+~~~
+enum FlowType: 
+	APPLICATION_FLOW  
+	| INTEGRATION_FLOW 
+	| SERVICE_ORCHESTRATION 
+	| API_CALL_SEQUENCING  
+	| EVENT_SOURCING
+;
+~~~
+ 
+~~~
+OrchestrationBinding:
+	'binding' /* 'flow' */ 'to' (eptb+=EndpointTypeBinding|cb+=ChannelBinding)+
+	('implemented' 'as' ft=FlowTechnology)?
+;
+~~~
+
+~~~
+FlowTechnology:
+	'APACHE_CAMEL_ROUTE' | 'SPRING_INTEGRATION_FLOW' 
+	| 'BPMN_PROCESS' | 'BPEL_PROCESS' | 'YET_ANOTHER_FLOW_LANGUAGE' 
+	| 'PLAIN_PROGRAMMING' | STRING 
+;
+~~~
+
+### Event types and command types
+
+Only event types and command types that have been declared can be used in flows. The syntax for these declarations is similar to that of the [data types](./datacontract) used in endpoint contracts:
+
+~~~
+EventTypes: 
+	'event' 'type' events+=EventType (',' events+=EventType)*
+;
+
+EventType:  
+	name=ID (content=ElementStructure)? // the domain data reported
+	('version' svi=SemanticVersioningIdentifier)?
+;
+
+CommandTypes:
+	'command' 'type' commands+=CommandType (',' commands+=CommandType)*
+;
+
+CommandType:
+	name=ID (subject=ElementStructure)? // in/out data or business object/item
+	('version' svi=SemanticVersioningIdentifier)?
+;
+~~~
+
+## Example
+
+This basic flow was actually generated from the [sample story scenario](./scenarios) with one of the quick fix [transformations](./soad.md) in the [MDSL tools](./tools.md).
+
+~~~
+flow Scenario1Flow realizes Scenario1
+event something_has_happened triggers command startProcess
+command startProcess emits event startProcessCompleted
+event CRUDSomeBusinessObjectTrigger triggers command CRUDSomeBusinessObject
+event startProcessCompleted triggers command startProcessCompletedProcessor
+command CRUDSomeBusinessObject emits event CRUDSomeBusinessObjectCompleted
+~~~
+
+See section "Processes and Event/Command Flows" in the [CML language reference](https://contextmapper.org/docs/application-and-process-layer/) for explanations.
+
+<!-- TODO document more advanced features: binding, type, ... -->
+
+# Site Navigation
+
+* Language specification: 
+    * [Scenarios and stories](scenarios.md)
+    * Service [endpoint contract types](./servicecontract) (this page) and [data contracts (schemas)](./datacontract)
+    * [Bindings](./bindings) and [instance-level concepts](./optionalparts)
+* [Quick reference](./quickreference), [tutorial](./tutorial) and [tools](./tools)
+* [MDSL homepage](./index)
+
+*Copyright: Olaf Zimmermann, 2018-2021. All rights reserved. See [license information](https://github.com/Microservice-API-Patterns/MDSL-Specification/blob/master/LICENSE).*
+
+<!-- *EOF* -->