DevOps YAML and JSON

YAML and JSON are text formats that store information in an organized way. Almost every DevOps tool reads one of them. Kubernetes, Docker Compose, Ansible, and GitHub Actions use YAML. Web services and cloud APIs use JSON.

Why These Formats Matter

Think of a paper form with labeled boxes. Each box has a label such as Name or City, and each label has an answer next to it. YAML and JSON work the same way. Each label is called a key, and each answer is called a value. Tools read these labels and values to learn what you want them to do.

Same Data in Both Formats

        YAML                         JSON
  -------------------        -----------------------
  name: web-app              {
  version: 2                   "name": "web-app",
  ports:                       "version": 2,
    - 80                       "ports": [80, 443]
    - 443                    }

Both blocks describe the same application. YAML looks cleaner for humans to read and write. JSON looks stricter and suits programs that exchange data.

YAML Basics

Key and Value Pairs

Write the key, a colon, a space, and the value.

app: shop
environment: production

Lists

Start each list item with a dash and a space. Keep every item at the same indentation level.

tools:
  - git
  - docker
  - terraform

Nested Data

Indentation shows structure. Indent a child key by two spaces under its parent.

database:
  host: db.example.com
  port: 5432

Comments

A hash symbol starts a comment. The tool ignores everything after it on that line.

# This setting controls the web port
port: 8080

JSON Basics

JSON wraps objects in curly braces and lists in square brackets. Keys must sit inside double quotes. Commas separate items, and the last item carries no comma. JSON does not allow comments.

{
  "app": "shop",
  "replicas": 3,
  "tools": ["git", "docker"],
  "database": { "host": "db.example.com", "port": 5432 }
}

Data Types

Real Example: A Kubernetes Snippet

apiVersion: v1
kind: Pod
metadata:
  name: demo-pod
spec:
  containers:
    - name: web
      image: nginx:1.27
      ports:
        - containerPort: 80

The file asks Kubernetes to start one pod. The pod runs one container built from the nginx image. A single wrong indent can change the meaning of the whole file, so careful spacing matters.

Choosing Between the Two

Pick YAML for files that people edit by hand, such as pipeline definitions and cluster settings. Pick JSON for data that programs send to each other, such as answers from a web service. Many tools accept both, and converters turn one format into the other in seconds. Learning both gives you the ability to read almost any DevOps configuration file.

Where You See Them in DevOps

Multi-Line Text and Reuse in YAML

The pipe symbol keeps line breaks in a block of text. The greater-than symbol joins the lines into one paragraph. Both help when a pipeline step holds several commands.

script: |
  echo "Step one"
  echo "Step two"

An anchor (&) names a block of settings, and an alias (*) reuses it. Reuse removes repeated lines and keeps files short.

defaults: &defaults
  restart: always
  timeout: 30

api:
  <<: *defaults
  name: api-service

Querying and Converting Data

The tool jq reads and filters JSON on the command line. The tool yq does the same job for YAML. Both save time when a file holds hundreds of lines.

echo '{"name":"web","port":80}' | jq '.port'
yq '.spec.replicas' deployment.yaml

Converters change YAML into JSON and back again. A pipeline script often reads a YAML file, extracts one value, and passes it to the next step.

Schemas and Validation

A schema is a rulebook that describes what a file must contain. A JSON Schema can demand that the key port exists and holds a number. Validators compare a file with the schema and report every problem.

 config.yaml --> [ Validator + Schema ] --> Pass: deploy
                                        --> Fail: show error list

Tools such as yamllint check style and syntax. Tools such as kubeconform check Kubernetes files against official schemas. Run these checks in the pipeline to catch a wrong indent before it reaches a server.

Syntax Gotchas

• YAML accepts spaces only, so a tab character breaks the file.
• YAML reads yes, no, and on as booleans in some tools. Wrap the word in quotes to keep it as text.
• JSON rejects a comma after the last item.
• JSON requires double quotes around every key.

Key Points

• YAML favors readability, and JSON favors strict structure.
• Indentation defines meaning in YAML.
• Braces, brackets, and quotes define meaning in JSON.
• Linting tools catch most format errors before deployment.