Author: Olaf Zimmermann, (c) 2018-2021. All rights reserved.

MDSL supports the API Description pattern from Microservice API Patterns (MAP) ("polyglot service design").

This is the "hello world" of cross-platform service contracting, specified in MDSL:

API description HelloWorldAPI data type SampleDTO {ID, D} endpoint type HelloWorldEndpoint exposes operation sayHello expecting payload D<string> delivering payload SampleDTO API provider HelloWorldAPIProvider1 offers HelloWorldEndpoint API client HelloWorldAPIClient1 consumes HelloWorldEndpoint 

As the example shows, the MDSL grammar defines two related specification languages:

1. An API description language: API endpoints types (a.k.a. service contracts types) can be defined, including their operations; API client and providers of instances of these endpoint types can be specified elaborately, including Service Level Agreements (SLAs).
2. A data contract language providing a type system for DTRs in request and response messages (which is very compact): data type SampleDTO {ID, D}.

These two languages can be used independently of each other; for instance, data contracts for operations in contract types can also be specified in JSON Schema (or XML Schema). Specifications do not have to be complete to be useful (e.g., in early stages of service design); tools will be expected to check that, use defaults, etc.

• The GitHub Pages for MDSL provide a tutorial and language reference information.
• There is an Eclipse update site for the MDSL editor.
• All generators are available via a Command Line Interface (CLI); see this readme and these examples.
• Presentations featuring Context Mapper, MAP and MDSL can be found here, and an end-to-end demo is available on Medium.
• As a contributor, please consult the readme file of the dsl-core project for getting started information and prerequisites.

• Overview
• Endpoint types (a.k.a. ports)
• Bindings (a.k.a. adapters)
• Data types (a.k.a. published language)
• Instance-level concepts (provider, client, gateway)

This repository contains:

• dsl-core, the DSL project, Xtext grammar and everything else needed to build an Eclipse plugin providing a MDSL editor.

• Various examples.
• The sources of the GitHub pages for MDSL.
• Some background information on other IDLs and related projects.

If you want to contribute to MDSL, you have to clone this repo and generate the required Xtext files.

Note: Setup and build process have been improved recently to ease integration with Context Mapper. As a consequence, the project has to be imported as an existing Maven project, and an adjustment of the IDE setup is required. The readme of the main project contains detailed instructions.

The current version of the MDSL language is 5.1; the tool version is 5.1.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).

See change log for an evolution history; see GitHub release notes for additional update information.

All Microservice API Patterns (MAP) are supported and integrated one way or another:

• As grammar rules
• As enums for roles and responsibilities
• As stereotypes annotating representation elements

See "MAP Decorators" section of the MDSL tutorial for more information.

The MDSL grammar, to be found in src folder of the dsl-core/io.mdsl project, was originally developed with Eclipse Photon (4.8.0) and Xtext (2.14) as provided by the Eclipse Modeling Platform. MDSL makes use of the referencing feature in Xtext ('name' attribute). Future work is required to also support this technology in other IDEs (such as Visual Studio Code).

Feedback and contributions welcome!

ZIO (a.k.a. socadk)

Contributors (input, DevOps support, feedback):

• Giacomo De Liberali (AsyncMDSL language, AsyncAPI generator)
• Stefan Kapferer (also the author of the MDSL generator in Context Mapper)
• MAP co-authors: Mirko Stocker, Daniel Lübke, Cesare Pautasso, Uwe Zdun
• Bachelor/master students at HSR/OST
• Microservices 2019 and VSS 2019 conference participants
• Early adopters and reviewers

The creation and release of MDSL 4 in 2020 was supported by the Hasler Foundation.

We are happy to welcome new contributors who want to help improve MDSL language and tools:

• Feel free to create issues in GitHub.
• Submit pull requests. If you do so, we assume that you comply with this Developer Certificate of Origin.
• Contact us to discuss collaboration and integration opportunities.

-- Olaf Zimmermann (ZIO)

Copyright: The author, 2019-2021. All rights reserved. See license information.