View on GitHub

Microservice DSL (MDSL)

A Domain-Specific Language (DSL) to specify (micro-)service contracts, their data representations and API endpoints.

Technology Mappings (Endpoint Level)

Note: This page contains incomplete, informal mappings. It is not part of the MDSL language specification, but intended to serves as background information for instance when working with the generator [tools]./tools).

RESTful HTTP (a.k.a. HTTP resource APIs)

Endpoints correspond to resources (with the mapping not being straightforward due to concepts such as URI templates and path parameters in HTTP). Operations correspond to HTTP verbs or methods (with additional constraints being imposed by the architectural style and nest practices for REST).

Web Services Description Language (WSDL)

MDSL endpoints map to port types in WSDL; operations (not surprisingly) to operations. API providers are pendants to ports in WSDL, API clients are service consumers.


The service contract grammar can easily be mapped to the glossary of Jolie terms. For instance, endpoint types in MDSL correspond to interfaces in Jolie:

Jolie MDSL/MAP Comments
Operation Operation n/a
Interface Endpoint type n/a
tbd API (multiple endpoint types) n/a
Port (inbound) API provider n/a
Port (outbound) API client n/a
(Micro-)Service (Micro-)Service exposes one or more APIs with one or more operations
Conversation Conversation to be checked
Service definition (service implementation) n/a
Service network tbd n/a
Cell and related concepts not in scope n/a

gRPC and Protocol Buffers

An endpoint type in MDSL corresponds to a gRPC service; MDSL operations correspond to gRPC messages.

Other integration technologies

MSDL service contracts can also be mapped to GraphQL, and Avro in a straightforward manner. Stay tuned!

Technology Mappings (Data Contract Level)


JSON MDSL Comments
Basic JSON data types Atomic Parameter Base types do not match 100%
Object (flat) Parameter Tree (flat) or Atomic Parameter List Parameter Tree preferred
Object (structured) Parameter Tree (nested) Straightforward
Array Cardinality of * or + Is homogeneous in MDSL/MAP

XML Schema

XML Schema MDSL/MAP Comments
Built-in data types Atomic Parameter Not the same expressiveness
Sequence element (referencing built-in types) Parameter Tree (flat) or Atomic Parameter List Parameter Tree preferred
Complex type Parameter Tree MDSL syntax more compact
Sequence with maxoccurs > 1 Cardinality of * or + n/a

gRPC and Protocol Buffers

The MAP base types can be mapped in a straightforward manner. AnyType is used as default.

Parameter forests and parameter trees translate into nested messages.


The MAP base types map to simple data in Jolie in a straightforward manner.

The same holds for the mapping of parameter trees to Jolie data structures.

An example can be downloaded here.