Microservice Domain-Specific Language (MDSL)

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

What is MDSL?

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, "someData": D<string>} 

endpoint type HelloWorldEndpoint
exposes 
  operation sayHello 
    expecting payload D<string>  
    delivering payload SampleDTO

API provider HelloWorldAPIProvider
  offers HelloWorldEndpoint at endpoint location "http://localhost:8080"
  via protocol HTTP binding resource Home at "/hello"

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, "someData": D<string>}. This type definition pairs an ID (without a name) with some string data.

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.

Getting Started

• The public 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.

Language Specification

The Primer is a good starting point. Detailed are explained on reference pages:

• Data types (a.k.a. published language)
• Endpoint types (a.k.a. ports)
• Protocol bindings (a.k.a. adapters)
• Instance-level concepts (provider, client, gateway)
• Integration scenarios and stories
• Orchestration flows
• A language extension supporting queue-based messaging endpoints is AsyncMDSL.

A Quick Reference providing reusable snippets is available as well.

Repository Structure

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.
• Background information: papers and presentations as well as information on relation to other IDLs and on related projects.

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

Note: 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. This setup and build process eases integration with Context Mapper.

Change Log

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).

The Change Log provides an evolution history; the GitHub Release Notes also contain update information.

Context Information: MAP and Xtext

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, located in the 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).

Feedback and contributions welcome!

ZIO (a.k.a. socadk)

Acknowledgements

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.

Getting involved

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-2022. All rights reserved. See license information.