Microservices Domain Specific Language (MDSL)

Note: Work in progress, subject to change at any time!

Design Goals

• Support agile modeling (in workshops, in iterations)
  • Allowing incomplete, partial specifications
• Support meet-in-the-middle service design
  • Top-down from requirements
  • Bottom up from existing systems
• Promote platform independence
  • Microservice API Patterns (MAP) as first-class language elements annotating/decorating endpoint types, operations, representation elements
  • Not bound to HTTP or other protocols (unlike Swagger and its successor Open API Specification) or message exchange formats

Design Principles

• Abstract language syntax inspired and driven by domain model and concepts of Microservice API Patterns (MAP)
• Elaborate concrete syntax in service contract part
• Compact and simple concrete syntax that abstracts from XML Schema, JSON Schema, etc. in data contract part¹

First Example

This is the Hello World of MDSL:

API description HelloWorld

data type SampleDTO (ID, E) 

endpoint contract type HelloWorldPort
exposes 
  operation helloWorld 
    expecting payload SampleDTO 
    delivering payload V<string> 
 
IPA

Take a look at Hello World in Swagger in comparison.

Language Features and Elements

• Service endpoint contract types
• Data contracts (schemas)
• Other concepts:
  • API Provider with Service Level Agreements and evolution strategies
  • API Client instances (basic support)
  • API Gateways (intermediaries)
  • Service compositions (experimental)

Language Reference (Sources)

• Quick reference a.k.a. grammar cheat sheet

• Full grammar
• Examples
• Project wiki

MSDL and MAP

All MAPs are supported/integrated one way or another:

• As grammar rules, e.g. ParameterTree, AtomicParameterList
• As enums for roles and responsibilities, e.g. PROCESSING_RESOURCE
• As stereotypes annotating representation elements, e.g. <<Embedded_Entity>>

We also like hexagons (although octogons, as used to denote cells in CBAs, look cool too):

External Links

• Public MAP website, access to team-internal preview website available upon request
• Lakeside Mutual repository, features Domain-Driven Design (DDD) and microservices in an insurance company scenario (JavaScript frontends and Spring Boot backends)
• Context Mapper, a DSL for strategic DDD

1. The 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). ↩