yq Session 01: Basics

Starting from zero. This session covers reading YAML files, output format conversion, and basic property access with yq.

Pre-Session State

  • Can read YAML structure (mappings, sequences, scalars)

  • Know basic shell piping

  • Have yq installed (sudo pacman -S yq)

Setup

cat > /tmp/yq-01.yaml << 'EOF'
name: domus-captures
version: "~"
title: Work Chronicles
start_page: ROOT:index.adoc

asciidoc:
  attributes:
    icons: font
    domain: inside.domusdigitalis.dev
    ad-dc-ip: 10.50.1.50
    ise-pan-ip: 10.50.1.20
    pfsense-ip: 10.50.1.1
    vlan-data: 10
    vlan-mgmt: 50

nav:
  - modules/ROOT/nav.adoc

tags:
  - documentation
  - antora
  - infrastructure
EOF

Lesson 1: Identity and Pretty Print

Concept: Like jq’s ., the identity expression returns the entire document.

Exercise 1.1: Read the whole file

yq '.' /tmp/yq-01.yaml

What happens: YAML is re-emitted with consistent formatting.

Exercise 1.2: Output as JSON

yq -o=json '.' /tmp/yq-01.yaml

Key insight: -o=json is the bridge from YAML to jq. This is the most important flag in yq.

Exercise 1.3: Output as props (key=value)

yq -o=props '.' /tmp/yq-01.yaml

Output: Flat key.subkey = value format. Useful for shell variable sourcing.

Lesson 2: Property Access

Concept: Same as jq — .key accesses a property.

Exercise 2.1: Top-level scalar

yq '.name' /tmp/yq-01.yaml

Output: domus-captures

Exercise 2.2: Nested access

yq '.asciidoc.attributes.domain' /tmp/yq-01.yaml

Output: inside.domusdigitalis.dev

Exercise 2.3: Access all attributes

yq '.asciidoc.attributes' /tmp/yq-01.yaml

Output: The full attributes mapping.

Lesson 3: Sequence (Array) Access

Concept: YAML sequences are arrays. Access with .[n] or .[].

Exercise 3.1: First tag

yq '.tags[0]' /tmp/yq-01.yaml

Output: documentation

Exercise 3.2: All tags

yq '.tags[]' /tmp/yq-01.yaml

Output: Each tag on its own line.

Exercise 3.3: Count tags

yq '.tags | length' /tmp/yq-01.yaml

Output: 3

Lesson 4: Type Checking

Concept: tag returns the YAML type tag, type returns the kind.

Exercise 4.1: Check types

yq '.name | type' /tmp/yq-01.yaml
yq '.asciidoc | type' /tmp/yq-01.yaml
yq '.tags | type' /tmp/yq-01.yaml
yq '.asciidoc.attributes.vlan-data | type' /tmp/yq-01.yaml

Output: !!str, !!map, !!seq, !!int

Exercise 4.2: Tag vs type

yq '.name | tag' /tmp/yq-01.yaml
yq '.name | type' /tmp/yq-01.yaml

tag returns the YAML tag (!!str). type returns the same. They’re equivalent for built-in types but differ for custom tags.

Lesson 5: The -o=json Pipeline

Concept: Convert YAML to JSON, then process with jq.

Exercise 5.1: yq to jq pipeline

yq -o=json '.asciidoc.attributes' /tmp/yq-01.yaml | jq 'to_entries[] | select(.value | tostring | test("10\\."))'

Output: Only attributes containing IP addresses.

Key insight: yq reads the YAML, -o=json converts it, jq does the heavy filtering. Best of both tools.

Summary: What You Learned

Concept Syntax Example

Identity

.

yq '.' re-emits YAML

JSON output

-o=json

yq -o=json '.' converts to JSON

Property access

.key

.name gets name field

Nested access

.key.subkey

.asciidoc.attributes.domain

Sequence index

.[n]

.tags[0] first element

All elements

.[]

.tags[] iterate sequence

Type check

type

.name | type returns !!str

Exercises to Complete

  1. [ ] Get the title as raw output

  2. [ ] Get all attribute keys (hint: .asciidoc.attributes | keys)

  3. [ ] Count how many attributes exist

  4. [ ] Pipe the attributes to jq and filter for VLANs

Next Session

Session 02: Filters - select, has, path filtering.

Session Log

Timestamp Notes

Start

<Record when you started>

End

<Record when you finished>