OpenWaymark

An open format for portable study bundles. Practice questions and flashcards are written in plain YAML, with local images, and packed into an ordinary ZIP file that any app can read.

Your study material should belong to you. An OpenWaymark bundle is something you can read, write, and keep without any particular app, account, or service. The format is documented openly, so anyone can build software that reads it.

  • Human-authorable. One study.yaml file, plus images in assets/.
  • Safe by design. Restricted Markdown, local images only, and nothing in a bundle can run as code.
  • Stable identity. Questions and cards keep their IDs across revisions, so notes and progress survive updates.
  • Independent. Implementing the format requires nothing from us, including any service or account.

A bundle at a glance

format_version: "0.1"
id: 6d5a39e7-9461-4c21-a736-f7b014b05783
title: Networking Fundamentals
version: 1.0.0
language: en

questions:
  - id: dns-record-001
    type: multiple_choice
    selection: single
    prompt:
      text: Which DNS record maps a hostname to an IPv4 address?
    choices:
      - id: record-a
        text: A
      - id: record-aaaa
        text: AAAA
    correct_answers: [record-a]
    explanation:
      text: An **A** record holds an IPv4 address; **AAAA** holds IPv6.

flashcards:
  - id: dns-card-001
    front:
      text: What does an AAAA record contain?
    back:
      text: An IPv6 address for a hostname.

Try the tools

The command-line tool checks a bundle against the format and packs it into a .waymark file. It needs Node.js 24 or later. To try it once without installing anything:

npx @automatethecloud/openwaymark validate my-bundle/

Or install it:

npm install --global @automatethecloud/openwaymark
openwaymark validate my-bundle/
openwaymark pack my-bundle/

The engine behind it, @automatethecloud/openwaymark-engine, runs in Node and in browsers, for your own programs. Every release is built and published from the project’s GitHub repository, and npm records a signed provenance statement linking it to the exact commit.

Where it stands

The format is a working draft, version 0.1. Field names may change until version 1.0, and the tools’ 0.x releases may break compatibility. Waymark Study is the first app that reads it.

Learn from it

The repository includes tutorials that start from zero: set up your computer, make a bundle, see how the validator works, and make your first code change, with tests. Its conformance fixtures explain every attack the validator stops, each as a short lesson in how files attack the programs that open them.

The specification, schema, fixtures, examples, engine, and tools are under the Apache License 2.0. The Waymark name and logos are not licensed. A study bundle is licensed by its author and states its own terms.