Swagger - Structured Data Formats

The Open API Specification uses the structured data format for its API definition files. We can use one of the two structured formats, either YAML or JSON.


YAML stands for Ain't Markup Language. It is not a Markup language like HTML. It is used for the data, not for the content. 

YAML uses minimum characters as compared to JSON and XML.

It is mainly used for the configuration files rather than the files which are passed over the web like JSON.

Key/value pairs in YAML file:-

The data in YAML is represented in the form of key/value pairs. Key/value pairs are indicated by a colon followed by a space.

For Example:

Date: 2021-07-08  

First name: John  

In the above example, Date and First Name are the keys, and 2021-07-08 and John are the values.


Levels are indicated by white space indenting, but we cannot use tab indent. This is the biggest difference between the YAML and the other structured formats. 

- XML uses tags that add one level, and inside the tag, there are other tags that add another level; so, this increases the number of characters.



      <firstname> John </firstname>  

      <lastname> Malik </lastname>  


- In JSON, opening and closing brackets indicate one level that occupies many characters.


name: {  

   "firstname": "John"  

   "lastname": "Malik"  

- In YAML, the only indentation is used, which occupies fewer characters.



  firstname: John  

  lastname: Malik  

YAML Types

The types in YAML are determined from the context.

For example:

part_no: A4786  

description: Photoresistor  

price: 1.47  

quantity: 4  

In the above scenario, part_no will be treated as a string, description will also be treated as a string, price will be treated as a floating type, and quantity will be treated as an integer.

Note: In YAML, we don't need quotes around the strings. There is one exception that if something is interpreted as a number or Boolean, then quotes are required.


List in YAML is similar to the JSON. We need to use a dash to indicate a list item.

We do not need to declare the list.


  -part_no: A4786  

   Description: Photoresistor  

   Price: 1.47  

   Quantity: 4  

-part_no: B3443  

   Description: LED  

   color: blue  

   price: 0.29  

   quantity: 12  

As we can observe in the above example, that cart is the name of the list, and there are two list items in the cart. Both the list items are represented by the dash. The first list item contains 4 key-value pairs, whereas the second list item contains 5 key-value pairs.

Multi-line Strings

As we know that strings do not contain quotation marks so we need special characters for multiline strings. The following are the characters used for the multi-line strings:

|: It preserves the lines and spaces.

>: It means fold lines.

S: |  


     and JSON.  

In the above example, we have used '|' character so its output would be same as it is written above.



   and JSON

If we use > character instead of '|' character:

 S: >


     and JSON.