YAML 101: just enough to edit an activity

Every Novedu activity is one YAML file, and every activity file is built from the same five patterns: keys with values, indentation, lists, multi-line text blocks, and comments. Once you can read those, you can open any sample activity, see what each line does, and change it with confidence. You don’t need the full YAML specification, and you don’t need to be a programmer.

All snippets in this chapter come from the real sample activities that ship with Novedu, so you can copy them as they are.

Keys and values

A YAML file is a list of named fields. Each line pairs a key, a colon, and a value:

id: ts-sorting-algorithms
name: "Tutor für Sortieralgorithmen (Bubble & Selection Sort)"
title: "Dein Tutor für Bubble Sort und Selection Sort"

The keys (id, name, title) are fixed by the activity format; you edit the values on the right. Values that are just true or false are written bare, in lowercase:

shuffle: false

When a value needs quotes

Simple values need no quotes: id: ts-sorting-algorithms works as it is. Put double quotes around a value in three cases:

The value contains a colon. Without quotes, YAML reads the colon as a second key and the file breaks. The sample sorting quiz quotes its name for exactly this reason:
```
name: "Quiz: Bubble Sort & Selection Sort"
```
The value looks like a number but should be text. An id such as 2024 would be read as a number; write id: "2024" to keep it as text. The safe habit is to give ids at least one letter, like quiz-2024.
You’re not sure. Quoting a text value is never wrong, so when in doubt, quote it.

Indentation shows nesting

Some fields group other fields under them. YAML shows that a field belongs to a group by indenting it, usually by two spaces per level:

llm:
  model: RedHatAI/gemma-4-31B-it-FP8-Dynamic

Here model sits inside the llm group because it is indented under it. Two rules keep this working:

Spaces only, never tabs. A tab character is invalid in YAML indentation and produces a confusing error. If your editor inserts tabs when you press the Tab key, change its setting to “insert spaces”.
Keep the depth consistent. Everything at the same level must start in the same column. When you copy lines around, check that they still line up.

Lists

A list puts each item on its own line, starting with a hyphen and a space. The simplest lists hold plain text, like the allowed topics in the sample sorting tutor:

allowed_topics:
  - "Bubble Sort: idea, passes, neighbor comparisons, swaps, early exit when no swap happens"
  - "Selection Sort: idea, finding the minimum in the unsorted part, swapping it to the front"

(These items are quoted because each contains a colon.)

A list item can also be a small group of fields. Then the hyphen starts the item and the item’s fields line up beneath it:

exampleQuestions:
  - title: "Wie funktioniert Bubble Sort?"
    question: "Kannst du mir Schritt für Schritt erklären, wie Bubble Sort ein Array sortiert?"
  - title: "Bubble vs. Selection Sort"
    question: "Was ist der Unterschied zwischen Bubble Sort und Selection Sort? Wann ist welcher besser?"

To add an item, copy an existing one and change the values. Keeping the indentation identical is what makes the copy work.

Multi-line text: the part you’ll write most

Instructions, descriptions, and prompts are usually several paragraphs long. YAML handles them with a pipe character (|) after the key: everything indented below it is one block of text, kept exactly as you type it, line breaks and blank lines included.

tutor_instructions: |
  You are a tutor for 16-year-old students at a vocational college. They are
  learning their first sorting algorithms: Bubble Sort and Selection Sort.

This is where most of your writing happens, and it is pleasantly forgiving: inside a | block you write normal text, with colons, quotes, lists, and Markdown, and none of it needs escaping. The only rule is that every line of the block stays indented under its key; the first line that is indented less ends the block.

Comments

A line starting with # is a comment: a note for humans that the app ignores. The sample files use comments to explain decisions, and you can too:

# The questions build up from concept to code, so keep the authored order.
shuffle: false

One caution: inside a | text block, a # is not a comment, it is part of your text and the AI will read it.

The three mistakes that actually bite

Almost every broken activity file comes down to one of these:

A tab instead of spaces. The file fails with an indentation error even though it looks fine on screen. Retype the indentation with the space bar, or set your editor to insert spaces.
A colon inside an unquoted value. A name like Quiz: Bubble Sort breaks the line unless you quote it: name: "Quiz: Bubble Sort".
A number-looking value that should be text. Quote it ("2024") or include a letter in it.

You don’t have to catch these by eye: your editor can check the file as you type, and the validator checks it again before any student sees the activity.

The idea behind YAML

JSON schemas in your editor

Check your activity with the CLI