View on GitHub


A domain-specific language to specify (micro-)service contracts and their data representations (realizing the API Description pattern from MAP)


Microservice Domain-Specific Language (MDSL) abstracts from technology-specific interface description languages such as Swagger, WSDL, and Protocol Buffers. Grammar, editor, tutorial, examples and a quick reference are available; tools are under construction.

Quick Start

A First Example

The Hello World of MDSL models an API with a single endpoint HelloWorldEndpoint that exposes a single operation called sayHello:

API description HelloWorldAPI

data type SampleDTO {ID, D} 

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

API provider HelloWorldAPIProvider1
  offers HelloWorldEndpoint

API client HelloWorldAPIClient1
  consumes HelloWorldEndpoint

sayHello accepts a single scalar string value D<string> as input. This operation returns a Data Transfer Object (DTO) called SampleDTO as output, which is modeled explicitly so that its specification can be reused. SampleDTO is specified incompletely: it must be an identifier-value pair, but the “parameter” names and the type of the value D have not been specified yet.

Take a look at Hello World in Swagger/Open API Specification in comparison. You can find such contract specification example here.

Design Goals

A contract language for (micro-)service API design should/must:

Design Principles

To achieve the above design goals, we decided that:

A Closer Look

Where and when to use MDSL

Let us visualize the usage context of MDSL specifications with two hexagons, as suggested by the microservices community:2

Solution Sketch of API Integration

If you want to leverage and promote microservices tenets such as polyglot programming and use multiple integration protocols, e.g., an HTTP resource API and message queuing, then MDSL is for you. The request and response message representations in the diagram can be specified with MDSL data contracts; the provided interface supports an MDSL endpoint type.

Language elements

  1. Service endpoint contract types follow this template: endpoint type ... exposes operation ... expecting ... delivering ...
  2. Data contracts (schemas): data type SampleDTO {ID, V} in the above example
  3. Other concepts:

See these concepts in action in the tutorial, the quick reference and on the examples page.

Usage of and support for Microservice API Patterns (MAP)

MDSL supports all Microservice API Patterns one way or another:

The four types of decorators/annotations and stereotypes are optional; if present, they make the API description more expressive and can be processed by tools (e.g., linters/validators, code/configuration generators, MDSL to Swagger/WSDL converters).


Ready to start/learn more? Click here.

More Information

MDSL Git Pages (this website)

Copyright: Olaf Zimmermann, 2018-2020. All rights reserved. See license information.

  1. The service and the data contract languages can be used independently of each other; for instance, data contracts for operations in contract types can also be specified in JSON Schema (but might not be supported by MDSL tools in that case). 

  2. Octogons, as used to denote cells in Cell-Based Architectures (CBAs), look cool too ;-)