====== YAML ======

**YAML (YAML Ain’t Markup Language)** is a human-readable data serialization language designed for simplicity and clarity.  
It is often used for configuration files, data exchange between programming languages, and declarative system descriptions (e.g., Docker Compose, GitHub Actions, Kubernetes).

===== History =====
YAML was first proposed in **2001** by **Clark Evans**, together with **Ingy döt Net** and **Oren Ben-Kiki**.  
The goal was to create a format that combined the **readability of plain text** with the **structure of JSON or XML**, making it easy for humans to write and understand while remaining machine-parsable.  
The acronym originally meant *"Yet Another Markup Language"*, but was later reinterpreted humorously as *"YAML Ain’t Markup Language"*, to emphasize that YAML focuses on **data**, not **documents** or **markup**.

===== Basic Idea =====
YAML is based on **indentation and key-value pairs**, allowing hierarchical (tree-like) data structures without the need for braces or brackets.  
It is often described as a **human-friendly alternative** to JSON and XML.

===== Comparison with JSON =====
^ Concept | JSON | YAML |
| Syntax | Uses braces `{}` and brackets `[]` | Uses indentation (spaces only) |
| Comments | Not allowed | Allowed with `#` |
| Readability | Machine-friendly | Human-friendly |
| Common use | APIs, web data exchange | Configuration, DevOps, CI/CD |

Example comparison:

<code json>
{
  "student": {
    "name": "Anna",
    "age": 21,
    "courses": ["Programming", "Databases"]
  }
}
</code>

<code yaml>
student:
  name: Anna
  age: 21
  courses:
    - Programming
    - Databases
</code>

===== Syntax Rules =====
  * Indentation defines structure (use spaces, not tabs)
  * Key-value pairs: `key: value`
  * Lists: prefix `-`
  * Nested structures: indent by two spaces
  * Comments: start with `#`

Example:
<code yaml>
server:
  host: localhost
  port: 8080
  enabled: true
  paths:
    - /login
    - /logout
</code>

===== Data Types =====

YAML supports a range of basic and complex data types.  
Values can be written in **implicit** or **explicit** form — YAML automatically detects the type from context, but types can also be specified manually using tags (e.g., `!!str`, `!!int`).

==== 1. Scalars ====
Scalars are single values such as strings, numbers, or booleans.

^ Type | Example | Notes |
| String | `name: "Alice"` | Quotation marks are optional unless special characters are used. |
| Integer | `age: 25` | No quotes needed; negative values allowed. |
| Float | `price: 19.99` | Decimal notation or scientific form (`1.2e+3`) supported. |
| Boolean | `enabled: true` or `enabled: no` | `true/false`, `yes/no`, and `on/off` are equivalent. |
| Null | `value: null` or `value: ~` | Both mean “no value”. |
| Date/Time | `created: 2025-11-03` | ISO 8601 format is recommended. |

Explicit typing (less common but useful for validation):
<code yaml>
id: !!int "42"
flag: !!bool "yes"
pi: !!float "3.14159"
text: !!str 1234   # forced as string, not number
</code>

==== 2. Strings ====
YAML offers flexible ways to define strings:

  * **Plain style:** `title: Hello World`

  * **Single-quoted:** `path: 'C:\Users\Name'`  
    (backslashes are preserved literally)

  * **Double-quoted:** `message: "Line1\nLine2"`  
    (supports escape sequences like `\n`, `\t`)

  * **Multi-line literal (`|`):** preserves line breaks  
    <code yaml>
    description: |
      This is line one.
      This is line two.
    </code>

  * **Folded block (`>`):** joins lines into a single paragraph  
    <code yaml>
    note: >
      This sentence
      continues on the next line.
    </code>

==== 3. Collections ====
YAML supports two structured types: **sequences (lists)** and **mappings (dictionaries)**.

  * **Sequences:** ordered lists of elements, marked with `-`
    <code yaml>
    colors:
      - red
      - green
      - blue
    </code>

  * **Mappings:** unordered key–value pairs
    <code yaml>
    person:
      name: Bob
      age: 30
      city: London
    </code>

  * **Inline form:** lists and dictionaries can also be written on one line  
    <code yaml>
    colors: [red, green, blue]
    person: {name: Bob, age: 30}
    </code>

==== 4. Nested Structures ====
Lists and mappings can be combined to represent complex hierarchical data:
<code yaml>
students:
  - name: Anna
    grades: [A, B, A]
  - name: Mark
    grades:
      - B
      - C
      - A
</code>

==== 5. Aliases and Anchors ====
YAML allows referencing the same data in multiple places using **anchors (&)** and **aliases (*)**.

<code yaml>
defaults: &base
  host: localhost
  port: 8080

development:
  <<: *base
  debug: true

release:
  <<: *base
  debug: false
</code>

This feature reduces duplication and keeps configuration files consistent.

==== 6. Summary ====
  * YAML automatically infers most types but supports explicit typing.
  * Scalars, sequences, and mappings cover all standard data models.
  * Multi-line and folded strings improve readability.
  * Anchors and aliases allow reuse of data blocks.


===== Validation and Schema =====
Just like JSON Schema, YAML files can be validated using schema definitions.  
Common tools include **Yamale**, **Kubeval**, or the built-in schema support of IDEs such as Visual Studio Code.

===== Typical Use Cases =====
  * **Docker Compose** (`docker-compose.yml`)
  * **GitHub Actions** (`.github/workflows/*.yml`)
  * **Kubernetes manifests** (`deployment.yaml`)
  * **Python and Node.js configuration files**

Example:
<code yaml>
version: "3.8"
services:
  web:
    image: nginx:latest
    ports:
      - "8080:80"
</code>



===== Summary =====
  * YAML is a **readable, indentation-based** language for structured data.
  * It was created to bridge the gap between human readability and machine processing.
  * It plays a central role in modern **DevOps**, **configuration management**, and **data description languages**.

----

===== JSON & YAML Exercises =====

==== 1. Identify the format & fix errors ====

**Task:**  
Determine whether the snippet is in JSON or YAML format. If invalid, fix it.

<code>
name: ChatGPT
skills: ["nlp", "reasoning", "qa"]
version: "5.1"
</code>

**Solution:**  
This is valid YAML.


==== 2. Convert JSON → YAML ====

**Task:**

<code json>
{
  "user": "John",
  "role": "student",
  "active": true,
  "points": 128
}
</code>

**Solution (YAML):**

<code yaml>
user: John
role: student
active: true
points: 128
</code>


==== 3. Convert YAML → JSON ====

**Task:**

<code yaml>
server:
  host: localhost
  port: 8080
  logging: true
</code>

**Solution (JSON):**

<code json>
{
  "server": {
    "host": "localhost",
    "port": 8080,
    "logging": true
  }
}
</code>


==== 4. Extend the YAML configuration ====

**Task:**  
Add an 'admins' list (min. 2 names) and an 'ssl' setting.

<code yaml>
webserver:
  host: 192.168.1.20
  port: 3000
</code>

**Solution:**

<code yaml>
webserver:
  host: 192.168.1.20
  port: 3000
  ssl: true
  admins:
    - alice
    - bob
</code>


==== 5. Valid or invalid JSON? Fix it. ====

**Task:**

<code json>
{
  "name": "Test app":
  "version": 1.0,
  "debug": true,
}
</code>

**Solution:**  
Errors: misplaced colon, trailing comma.

Correct version:

<code json>
{
  "name": "Test app",
  "version": 1.0,
  "debug": true
}
</code>


==== 6. Fix the indentation errors (YAML) ====

**Task:**

<code yaml>
database:
    name: testdb
      port: 5432
  host: localhost
</code>

**Solution:**

<code yaml>
database:
  name: testdb
  port: 5432
  host: localhost
</code>


==== 7. Create the JSON structure ====

**Task:**  
Create this structure in JSON:

  * application
    * name: "ProdApp"
    * database:
      * host: "10.0.0.12"
      * port: 3306
      * users: ["admin", "guest"]

**Solution:**

<code json>
{
  "application": {
    "name": "ProdApp",
    "database": {
      "host": "10.0.0.12",
      "port": 3306,
      "users": ["admin", "guest"]
    }
  }
}
</code>


==== 8. Rewrite "sizes" as a list ====

**Task:**

<code yaml>
product:
  name: hoodie
  sizes: "S, M, L, XL"
</code>

**Solution:**

<code yaml>
product:
  name: hoodie
  sizes:
    - S
    - M
    - L
    - XL
</code>


==== 9. Create your own configuration ====

**Task:**  
Create a configuration (YAML or JSON) including:

  * server settings
  * 3 users
  * roles
  * features list (3 items)

**Solution (YAML example):**

<code yaml>
app:
  server:
    host: 0.0.0.0
    port: 5000

  users:
    - name: anna
      role: admin
    - name: bela
      role: editor
    - name: koris
      role: read-only

  features:
    - analytics
    - backup
    - notifications
</code>


==== 10. List differences between JSON and YAML ====

**Task:**  
List 5 differences.

**Solution:**

  * YAML uses indentation instead of curly braces.
  * YAML supports comments (#), JSON does not.
  * JSON has stricter syntax; YAML is more flexible.
  * YAML supports advanced features (anchors, aliases).
  * JSON keys must be strings; YAML keys do not require quotes.


==== 11. Industrial config conversion ====

**Task:** Convert to YAML and add `backup: true`.

<code json>
{
  "plant": "Factory_A",
  "machines": [
    {"id": 1, "type": "CNC", "status": "online"},
    {"id": 2, "type": "Laser", "status": "offline"}
  ],
  "schedule": {
    "shift": "night",
    "workers": 12
  }
}
</code>

**Solution:**

<code yaml>
plant: Factory_A
machines:
  - id: 1
    type: CNC
    status: online
  - id: 2
    type: Laser
    status: offline
schedule:
  shift: night
  workers: 12
backup: true
</code>


==== 12. Convert string booleans to real booleans ====

**Task:**

<code yaml>
config:
  verbose: "true"
  auto_restart: "false"
  safe_mode: "False"
</code>

**Solution:**

<code yaml>
config:
  verbose: true
  auto_restart: false
  safe_mode: false
</code>