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
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
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.
<name>
<firstname> John </firstname>
<lastname> Malik </lastname>
</name>
- In JSON, opening and closing brackets indicate one level that occupies many characters.
JSON:
name: {
"firstname": "John"
"lastname": "Malik"
}
- In YAML, the only indentation is used, which occupies fewer characters.
YAML
name:
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
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.
cart:
-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: |
YAML
and JSON.
In the above example, we have used '|' character so its output would be same as it is written above.
Output
YAML
and JSON
If we use > character instead of '|' character:
S: >
YAML
and JSON.
Output
YAML and JSON