@shayc/open-board-format

A TypeScript toolkit for Open Board Format — the open standard for Augmentative and Alternative Communication (AAC) boards. Parse, validate, and create OBF boards and OBZ packages, all backed by Zod schemas with full TypeScript types inferred.

OBF (.obf) is a JSON file describing a single communication board — buttons, images, sounds, grid layout, metadata. OBZ (.obz) is a ZIP archive bundling one or more .obf boards with their media and a manifest.json.

Install

npm install @shayc/open-board-format

Quick start

import { parseOBF } from "@shayc/open-board-format";

const board = parseOBF(jsonString);
console.log(board.id, board.buttons.length);

parseOBF throws on invalid input; the returned value is a fully typed OBFBoard. For other input shapes (already-parsed object, browser File, OBZ archive), see Overview.

Overview

Two file types; pick the entry point by what you have:

• OBF is a single board (a JSON object). Use parseOBF for a JSON string, validateOBF for an already-parsed object, loadOBF for a browser File. stringifyOBF serializes back out.
• OBZ is a package of boards plus media (a ZIP archive). Use loadOBZ for a File, extractOBZ for an ArrayBuffer, createOBZ to build a new one.

Every OBF type ships with a matching *Schema Zod schema (e.g. OBFBoardSchema, OBFManifestSchema), so you can validate inline with safeParse or wire the schema straight into an API contract — the TypeScript types are inferred from those schemas.

Validation preserves unknown fields rather than stripping them, so vendor extensions allowed by the OBF spec survive a parseOBF → stringifyOBF round trip.

Requirements

• Module format: ESM only.
• Runtime: browser or Node 22+ — works against File, ArrayBuffer, and Blob.

Examples

Extract an OBZ package

import { loadOBZ, extractOBZ } from "@shayc/open-board-format";

// From a File (e.g. drag-and-drop)
const { manifest, boards, resources } = await loadOBZ(file);

// Or from an ArrayBuffer (e.g. fetch response)
const parsed = await extractOBZ(buffer);

const homeBoard = parsed.boards.get("1");
const imageBytes = parsed.resources.get("images/logo.png");

Create an OBZ package

import { createOBZ } from "@shayc/open-board-format";
import type { OBFBoard } from "@shayc/open-board-format";

const boards: OBFBoard[] = [
  {
    format: "open-board-0.1",
    id: "board-1",
    buttons: [{ id: "btn-1", label: "Hello" }],
    grid: { rows: 1, columns: 1, order: [["btn-1"]] },
  },
];

const pngBytes = new Uint8Array(/* ... */);
const resources = new Map([["images/logo.png", pngBytes]]);
const blob = await createOBZ(boards, "board-1", resources);

Validate with Zod directly

import { OBFBoardSchema } from "@shayc/open-board-format";

const result = OBFBoardSchema.safeParse(data);

if (result.success) {
  console.log(result.data.buttons);
} else {
  console.error(result.error.issues);
}

API

OBF (single board)

| Function | Description | | --------------------- | ------------------------------------------------------------ | | parseOBF(json) | Parse a JSON string into a validated OBFBoard | | validateOBF(data) | Validate an unknown object as OBFBoard (throws on failure) | | stringifyOBF(board) | Serialize an OBFBoard to a JSON string | | loadOBF(file) | Load an OBFBoard from a browser File |

OBZ (board package)

| Function | Description | | -------------------------------------------- | ------------------------------------------------------------- | | loadOBZ(file) | Load an OBZ package from a browser File | | extractOBZ(archive) | Extract boards, manifest, and resources from an ArrayBuffer | | createOBZ(boards, rootBoardId, resources?) | Create an OBZ package as a Blob | | parseManifest(json) | Parse a manifest.json string into a validated OBFManifest |

Utilities

| Function | Description | | ---------------- | -------------------------------------------------------- | | isZip(archive) | Check if an ArrayBuffer starts with a ZIP magic number | | zip(entries) | Create a ZIP from a map of paths to buffers | | unzip(archive) | Extract a ZIP into a map of paths to Uint8Array |

Types

| Type | Description | | --------------------- | --------------------------------------------------------------------------- | | OBFBoard | A single communication board | | OBFGrid | Grid layout (rows, columns, order) | | OBFButton | A button on the board | | OBFButtonAction | Button action (spelling or specialty) | | OBFSpellingAction | Spelling action (e.g., +s) | | OBFSpecialtyAction | Specialty action (e.g., :clear) | | OBFLoadBoard | Reference to load another board | | OBFMedia | Common media properties (base for OBFImage and OBFSound) | | OBFImage | An image resource (extends OBFMedia) | | OBFSound | A sound resource (extends OBFMedia) | | OBFSymbolInfo | Symbol set reference | | OBFManifest | OBZ package manifest | | ParsedOBZ | Return type of extractOBZ / loadOBZ — { manifest, boards, resources } | | OBFID | Unique identifier (string, coerced from number) | | OBFFormatVersion | Format version string (e.g., open-board-0.1) | | OBFLicense | Licensing information | | OBFLocaleCode | BCP 47 locale code | | OBFLocalizedStrings | Key-value string translations | | OBFStrings | Multi-locale string translations |

Schemas

Every type above except ParsedOBZ is exported alongside a matching Zod schema with a Schema suffix — OBFBoard → OBFBoardSchema, OBFManifest → OBFManifestSchema, and so on. Import any of them to validate with safeParse/parse or to compose into your own schemas:

import { OBFButtonSchema, OBFManifestSchema } from "@shayc/open-board-format";

Errors

All failures throw plain Error. The message identifies what failed, typically with one of these prefixes:

• Invalid OBF: — schema validation rejected an OBF board.
• Invalid OBZ: — the package was rejected. On read: not a ZIP, missing manifest, or the manifest references a board file not in the archive. On write (createOBZ): rootBoardId matches no board, a board fails validation, two boards map the same media id to conflicting paths, a declared image/sound path has no matching resource, or a resource would overwrite a generated entry.
• Invalid manifest: — manifest.json failed to parse or validate.

When the root cause is a JSON.parse failure, the original error is preserved as error.cause. For finer-grained validation, drop one level down and use the Zod schemas directly with safeParse — the issues array tells you exactly which field failed.

Security

OBZ archives are untrusted input. This library does not enforce limits on entry size or count, and does not sanitize entry paths — if you write extracted resources to disk, validate paths yourself first to avoid directory traversal. For stronger guarantees against zip-bomb-style payloads, run extraction in a sandboxed context (Web Worker, isolated process).

Found a security issue? Open a private advisory at github.com/shayc/open-board-format/security/advisories/new.

Versioning

Semver; see CHANGELOG.md.

Contributing

See CONTRIBUTING.md for development setup (Node 22+, Vitest, the changeset workflow).

Related

• Open Board Format specification — the official standard and format documentation.
• AAC Board AI — an offline-first AAC web app built on this package, using on-device browser AI for grammar, tone, and translation (live app).

License

MIT © Shay Cojocaru