View on GitHub

MDSL

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

MDSL Grammar Examples

Service Contract

The following exemplary API specification compiles against the MDSL grammar:

API description SampleCustomerManagementAPI
usage context PUBLIC_API for FRONTEND_INTEGRATION 

endpoint type CustomerManagementContract
  version 1.0.0  
  serves as INFORMATION_HOLDER_RESOURCE
  exposes 
  	operation lookupSingleCustomer 
	  with responsibility RETRIEVAL_OPERATION 
	  expecting 
		payload ID<string> 
	  delivering  
		payload {"customerId":ID<int>,
		          "name":V,
		          "address"} 
				
  	operation lookupCustomerDirectory
	  with responsibility RETRIEVAL_OPERATION
	  expecting 
		payload <<Request_Bundle>> "customerId":ID<int>+ 
	  delivering
		payload
		  "customerRecord": { 
			"cid":ID!, // ! mandatory, exactly one
			"nameTuple":("firstname":V, "lastname":V), 
			"addressTuple":(
			  "street":V<string>, 
			  "poBox":V?, // optional
			  "zipCode":V, 
			  "city":V)+,
			"segment":("REGULAR":V|"VIP":V) // choice 
		}* // zero or more

Data Contract

The following simple examples feature the structural language primitives and give instantiation examples (in the comments):

data type SomeAtomicParameter V 
// yields any string or numeric literal: "A", 1, true

data type SomeNumber V<int> 
// yields 1

data type SomeStructuredRecord {SomeFlatRecord, SomeNumber} 
// yields { ("A", 1, true), 42 }

data type TwoNestingLevels {SomeStructuredRecord, SomeAtomicParameter} 
// yields { {("A", 1, true), 42}, "A" }

data type SomeFlatRecord (V<string>, V<int>, V<boolean>) 
// yields ("A", 1, true)

data type ChoiceDemo {"optionA":V|"optionB":V}

Quick reference skeletons.

More on service endpoint contract types and data contracts (schemas). Instance-level language constructs.

Back to MDSL homepage.

Copyright: Olaf Zimmermann, 2019. All rights reserved.