OpenWaymark

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

---

Your study material should belong to you. An OpenWaymark bundle is a set of practice questions and flashcards 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 Waymark, including any service or account.

Install the tools

You do not need to clone this repository to check or pack bundles. The command-line tool and the engine are published on npm, and need Node.js 24 or later.

The command-line tool, @automatethecloud/openwaymark:

npm install --global @automatethecloud/openwaymark
openwaymark validate my-bundle/       # Does it follow the format?
openwaymark pack my-bundle/           # Make my-bundle.waymark

Or try it once without installing anything:

npx @automatethecloud/openwaymark validate my-bundle/

The CLI guide covers every command, the exit statuses, and malware scanning.

The engine, for your own programs, @automatethecloud/openwaymark-engine:

npm install @automatethecloud/openwaymark-engine

It runs in Node and in browsers. The engine guide shows how to validate a bundle in a few lines.

Check where a release came from. Every release is built and published by this repository's GitHub Actions workflow, and npm records a signed provenance statement that links it to the exact commit. npm audit signatures, run in a project that installs the packages, verifies them.

The engine and the CLI share one version number. The format is a working draft, so expect breaking changes in 0.x releases. If your project only installs packages after they have been public for some days (pnpm's minimumReleaseAge, for example), a new release becomes available to it once that time has passed.

Want to change the code, or run the tests? Clone the repository and see Development.

Learn by doing

New to all of this? docs/learn/ starts from zero: set up your computer, make a bundle, see how the validator works, and make your first code change, with tests. Not a developer yet? These tutorials are written for you.

Every attack the validator stops is explained in fixtures/README.md, as a short lesson in how files attack the programs that open them.

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
      - id: record-cname
        text: CNAME
    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.

The format is a working draft. Field names may change until version 1.0.

What's here

Path	Contents
spec/	The OpenWaymark specification, authoring guide, and change log
schema/	JSON Schema for the manifest, drafts 0.1 and 0.2
examples/	Valid example bundles, as folders: IT, high-school, rendering, and language learning
fixtures/	Conformance fixtures for implementers, each a lesson in one attack or mistake
packages/engine	Reference engine: validation, linting, and package inspection. It runs in Node and in browsers
packages/cli	openwaymark command-line tool: validate, lint, inspect, scan, pack

The engine and the CLI are on npm; see Install the tools.

The browser validator checks and packs bundles on your own device, without installing anything and without uploading your files.

Waymark Study, an offline study app by Automate the Cloud, is the first application that reads OpenWaymark bundles. It is in development and not yet public.

Development

To work on the code itself, clone the repository. Requires Node 24 and pnpm (the version is pinned in package.json).

pnpm install
pnpm check      # typecheck, lint, format, tests, spelling, license headers

Script	What it does
pnpm build	Compile every package (tsc --build)
pnpm test	Build, then run the Vitest suites
pnpm lint	ESLint with type-aware rules
pnpm format	Format with Prettier
pnpm spelling	Fail on British spellings in text files
pnpm headers	Fail on source files without the copyright and SPDX header

Dependencies are installed only after they have been public for 7 days (minimumReleaseAge in pnpm-workspace.yaml). Dependency install scripts do not run unless they are allowlisted there.

License

The specification, schema, fixtures, examples, engine, CLI, and browser validator are licensed under the Apache License 2.0. Copyright 2026 Automate the Cloud Inc.; see NOTICE.

Not licensed: the Waymark and Waymark Study names, and the logo files in .github/brand/, are property of Automate the Cloud Inc. The Apache License grants no trademark rights (§6), and those files are excluded from it.

Study bundles are licensed by their authors and are not covered by this repository's license. A bundle states its own terms in its license field.