Write schema in an easy, concise and short way.
Writing OpenAPI Schema can be tiresome and time wasting task if you write a lot of API Documentation. Updating existing Schema can also be cumbersome and confusing especially when project grows to hundreds of APIs. TSSG is here to help you write schema in an easy, clean and concise way. We have proposed a new and easy to understand Syntax/Grammar for this. It allows you to write less and get full OpenAPI Schema without writing and repeating same line again and again.
Our aim is to build a tool that helps you in splitting your APIs Schemas and Endpoints Definitions into separate files so that it's easy to maintain and update/edit the target APIs.
Below is our roadmap:
- TSSG Syntax Parser (Alpha Version released)
- TSSG to OpenAPI Transformer (Alpha Version released)
- TSSG Editor (Alpha Version released)
- OpenAPI to TSSG Syntax Transformer (WIP)
- TSSG CLI (WIP)
Consider the following object Schema of User
:
{
"type": "object",
"properties": {
"name": {
"type": "string"
},
"age": {
"type": "number"
},
"email": {
"type": "string"
},
"address": {
"type": "object",
"properties": {
"street": {
"type": "string"
},
"city": {
"type": "string"
},
"country": {
"type": "string"
},
"zipcode": {
"type": "string"
}
}
}
}
}
The above schema has a lot of repetition and if the schema is more complex that have nested object or array of object, it gets more complex to write.
On the other hand, with TSSG, above schema can be written as:
{
name: string,
age: number,
email: string,
address: {
street: string,
city: string,
country: string,
zipcode: string,
}
}
We hope, we don't need to explain above syntax. It's already understandable and easy to type and read.
You only need to mention the type of the property and it will be tranformed to { "type": "string" }
form.
Following data types are support as of now:
- string
- number
- integer
- boolean
- {} (shorthand for object type)
- [] (shorthand for array)
Required Properties
Let's take the above example again, and add some properties as required.
{
"type": "object",
"required": ["name", "email", "address"],
"properties": {
"name": {
"type": "string"
},
"age": {
"type": "number"
},
"email": {
"type": "string"
},
"address": {
"type": "object",
"required": ["country"],
"properties": {
"street": {
"type": "string"
},
"city": {
"type": "string"
},
"country": {
"type": "string"
},
"zipcode": {
"type": "string"
}
}
}
}
}
In the above schema, we have name
, email
and address
as required property and inside the address
object we have country
as required.
To write the above schema, you can simply do the following:
{
name: !string,
age: number,
email: !string,
address: !{
street: string,
city: string,
country: !string,
zipcode: string,
}
}
You can mark a property as required
by using !
(exclamation mark) in front of data type. Above mentioned syntax will produce the exact same OpenAPI Schema shown above example.
Notice
!
in the start of address value.
Arrays
Consider this simple example which accepts data
property of type array of string
.
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
Above schema can be written in TSSG as follows:
{
data: [string]
}
Look, how simple it is to define array of string
in one simple line.
You can also mark data
property as required using !
sign.
{
data: ![string]
}
Above TSSG syntax will produce following Schema:
{
"type": "object",
"required": ["data"],
"properties": {
"data": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
Array of Objects
Consider the following schema:
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"age": {
"type": "number"
},
"email": {
"type": "string"
},
"address": {
"type": "object",
"required": ["country"],
"properties": {
"street": {
"type": "string"
},
"city": {
"type": "string"
},
"country": {
"type": "string"
},
"zipcode": {
"type": "string"
}
}
}
}
}
}
}
}
Above schema can be written in TSSG as follow:
{
data: [{
name: string,
age: number,
email: string,
address: {
street: string,
city: string,
country: string,
zipcode: string,
}
}]
}
If
data
property is required, just mark that required using!
sign.
Enums
You can use the enum keyword to specify possible values of a request parameter or a model property. For example, consider the following schema:
{
"type": "object",
"properties": {
"colors": {
"type": "string",
"enum": [
"red",
"green",
"blue"
]
}
}
}
Above schema can be written in TSSG as follows:
{
colors: enumOf(string, "red", "green", "blue"),
}
Thanks goes to these wonderful people (emoji key):
![]() Tauqeer Nasir π» π§ π π‘ |
![]() Akshat Sharma π» π π‘ π§ |
![]() Ming Hu π» π‘ π§ |