JSON schemas in your editor
Writing an activity file by hand is much easier when your editor knows which fields exist. A short one-time setup gives you suggestions as you type, warnings when something is wrong, and a short explanation of every field, all before you upload anything to Novedu.
What the editor gives you
Section titled “What the editor gives you”With schema support switched on, your editor helps you in three ways:
- Suggestions as you type. Start typing at the top level of the file and the editor offers the field names that belong there, so you don’t have to remember them.
- Red underlines for mistakes. A misspelt field name, or a value of the wrong type (for example, plain text where a list is expected), gets underlined right away.
- Help on hover. Move the mouse over a field name and the editor shows a short description of what the field does.
Install the YAML extension (one time)
Section titled “Install the YAML extension (one time)”Schema support comes from the free YAML extension by Red Hat. You install it once; after that it works for every activity file you open.
- Open VS Code.
- Open the Extensions view (Ctrl+Shift+X).
- Search for YAML and select the extension published by Red Hat.
- Select Install.
You can also install it from the Red Hat YAML extension page on the Visual Studio Marketplace.
Add the schema line to your file
Section titled “Add the schema line to your file”The editor learns which fields your file may contain from a special comment on the first line of the file. For a tutor, the sample activities start like this:
# yaml-language-server: $schema=https://raw.githubusercontent.com/Teaching-HTL-Leonding/novedu-chat-mvp/refs/heads/main/activities/tutors/tutor-yaml.schema.jsonCopy the line exactly as it is, including the leading #. It is a comment, not a field: Novedu ignores it completely, and students never see it. Only your editor reads it, fetches the schema from that address over the internet, and switches on the suggestions, underlines, and hover help. The easiest way to get the line right is to start from one of the sample activities, which all carry it already.
Which schema for which kind of activity
Section titled “Which schema for which kind of activity”There is a separate schema for each kind of file, and the line has to match the kind you are writing. With the wrong schema, the editor underlines fields that are perfectly valid, so if everything suddenly looks wrong, check the first line first.
For a tutor:
# yaml-language-server: $schema=https://raw.githubusercontent.com/Teaching-HTL-Leonding/novedu-chat-mvp/refs/heads/main/activities/tutors/tutor-yaml.schema.jsonFor a library of fragments. A fragment library is not a tutor and has its own schema, even though tutors are where you use fragments most:
# yaml-language-server: $schema=https://raw.githubusercontent.com/Teaching-HTL-Leonding/novedu-chat-mvp/refs/heads/main/activities/fragments/fragment-yaml.schema.jsonFor a quiz:
# yaml-language-server: $schema=https://raw.githubusercontent.com/Teaching-HTL-Leonding/novedu-chat-mvp/refs/heads/main/activities/quizzes/quiz-yaml.schema.jsonFor a writing activity:
# yaml-language-server: $schema=https://raw.githubusercontent.com/Teaching-HTL-Leonding/novedu-chat-mvp/refs/heads/main/activities/writings/writing-yaml.schema.jsonFor a coding activity:
# yaml-language-server: $schema=https://raw.githubusercontent.com/Teaching-HTL-Leonding/novedu-chat-mvp/refs/heads/main/activities/coding/coding-yaml.schema.jsonThere is one more schema, for a file that is not an activity: the activity registry, the list of activities you keep next to a book or a course repository. If you write one, it takes this line:
# yaml-language-server: $schema=https://raw.githubusercontent.com/Teaching-HTL-Leonding/novedu-chat-mvp/refs/heads/main/activities/registry/registry-yaml.schema.jsonThe editor helps, Novedu decides
Section titled “The editor helps, Novedu decides”Schema support in the editor is a comfort feature: it catches most typos while you write. Novedu still runs its own, stricter checks when you save a file, and those checks are the ones that count. A file with no red underlines can still be rejected (for example, when a tutor refers to a fragment that doesn’t exist), so treat the editor’s hints as a first pass, not as final approval.