next is using a (subset) of typescript for human consumption and concert that to json for machine consumption

because one thing is for sure, json schema and openapi are not really nicely readable, even if written as yaml