@shayc/open-board-format

A TypeScript toolkit for Open Board Format — the open standard for Augmentative and Alternative Communication (AAC) boards. 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 boards with their media and a manifest.json. This package parses, validates, and creates both.

my-board.obz
├── manifest.json        ← table of contents: root board + id-to-path maps
├── boards/
│   └── home.obf         ← one JSON board per file
├── images/
│   └── dog.png
└── sounds/
    └── hello.mp3

• Typed end to end — every type is inferred from a Zod schema, and every schema is exported for safeParse or composing into your own contracts.
• Browser and Node.js 22+ — pure ESM, works against File, Blob, ArrayBuffer, or any typed-array view (e.g. Node's Buffer).
• One entry point for either format — loadBoard sniffs the bytes and tells you whether it found an .obf board or an .obz package.
• Spec-faithful round trips — unknown fields are preserved rather than stripped, so vendor extensions allowed by the OBF spec survive parseOBF → stringifyOBF.
• Small footprint — one runtime dependency (fflate) plus Zod as a peer, tree-shakeable, no side effects.

Contents: Install · Quick start · Usage · API · Errors · Security · Scope · Versioning · Contributing · Related · License

Install

npm install @shayc/open-board-format zod

zod 4 is a peer dependency — npm 7+ installs it automatically, but pnpm and Yarn users should add it explicitly (as shown above).

ESM only — CommonJS (require) is not supported.

Quick start

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

// `file` came from drag-and-drop or <input type="file"> — could be .obf or .obz
const loaded = await loadBoard(file);

if (loaded.format === "obf") {
  console.log(loaded.board.buttons.length);
} else {
  console.log(loaded.archive.rootBoard.buttons.length);
}

loadBoard accepts a File, Blob, ArrayBuffer, or any typed-array view (e.g. a Node Buffer), and throws on invalid input (see Errors). Already holding a JSON string? parseOBF(json) returns a validated OBFBoard directly.

In Node.js, read the file first — there's no File API outside the browser, but readFile's Buffer works directly:

import { readFile } from "node:fs/promises";
import { loadBoard } from "@shayc/open-board-format";

const loaded = await loadBoard(await readFile("my-board.obz"));

Usage

Which function do I need?

• You have a single board (OBF). Use parseOBF for a JSON string, validateOBF for an already-parsed object, loadOBF for a browser File. stringifyOBF serializes back out.
• You have a package of boards plus media (OBZ). Use extractOBZ for a File, Blob, ArrayBuffer, or typed-array view (loadOBZ is the same thing, File-only); createOBZ to build a new one.
• You don't know which you have. Use loadBoard — it sniffs the bytes and returns a { format, ... } union so you don't have to inspect the file extension yourself.

Read an OBZ package

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

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

// Or from anything else — ArrayBuffer, Blob, Node Buffer, etc.
const parsed = await extractOBZ(buffer);

// Untrusted input? Cap declared uncompressed sizes (see Security)
const guarded = await extractOBZ(buffer, {
  limits: { maxTotalOriginalSize: 500e6 },
});

rootBoard is the package's home board — the one manifest.root points at, already resolved. boards is keyed by board ID and resources by archive path; the manifest is also returned if you need the raw table of contents.

Resources are raw bytes. To display an image in the browser:

const bytes = resources.get("images/hello.png")!;
const url = URL.createObjectURL(new Blob([bytes]));

Create an OBZ package

Buttons reference media by ID (image_id, sound_id); the board's images/sounds entries carry the archive path; the resources map supplies the bytes for each path. Every path a board declares must have a matching resource entry, or createOBZ throws.

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

const board: OBFBoard = {
  format: "open-board-0.1",
  id: "board-1",
  buttons: [{ id: "btn-1", label: "Hello", image_id: "img-1" }],
  grid: { rows: 1, columns: 1, order: [["btn-1"]] },
  images: [{ id: "img-1", path: "images/hello.png" }],
};

const pngBytes = new Uint8Array(/* ... */);
const resources = new Map([["images/hello.png", pngBytes]]);

const blob = await createOBZ([board], "board-1", resources);

The manifest.json is generated for you — boards are written to boards/<id>.obf (the id is percent-encoded, so it's always a safe filename), and rootBoardId (the second argument) selects the home board.

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

One naming convention covers the whole surface: parse* takes a JSON string, validate* takes an already-parsed object, load* takes a browser File, stringify* returns a JSON string — and extractOBZ/loadBoard also accept a Blob, ArrayBuffer, or typed-array view (e.g. a Node Buffer), for use outside the browser.

OBF (single board)

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

OBZ (board package)

| Function | Returns | Description | | -------------------------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------- | | loadOBZ(file, options?) | Promise<ParsedOBZ> | Load an OBZ package from a browser File | | extractOBZ(archive, options?) | Promise<ParsedOBZ> | Extract boards, manifest, root board, and resources from a File, Blob, ArrayBuffer, or typed-array view | | createOBZ(boards, rootBoardId, resources?) | Promise<Blob> | Create an OBZ package as a Blob | | parseManifest(json) | OBFManifest | Parse a manifest.json string into a validated OBFManifest |

Format detection

| Function | Returns | Description | | ---------------------------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------- | | loadBoard(input, options?) | Promise<LoadedBoard> | Detect OBF vs OBZ from a File, Blob, ArrayBuffer, or typed-array view and load it; returns a LoadedBoard union |

Utilities

| Function | Returns | Description | | -------------------------- | ---------------------------------- | -------------------------------------------------------- | | isZip(archive) | boolean | Check if an ArrayBuffer starts with a ZIP magic number | | zip(entries) | Promise<Uint8Array> | Create a ZIP from a map of paths to buffers | | unzip(archive, options?) | Promise<Map<string, Uint8Array>> | 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 (alias of OBFMedia) | | OBFSymbolInfo | Symbol set reference | | OBFManifest | OBZ package manifest | | ParsedOBZ | Return type of extractOBZ / loadOBZ — { manifest, boards, rootBoard, resources } | | LoadedBoard | Return type of loadBoard — { format: "obz", archive } \| { format: "obf", board } | | BinaryInput | Input type of loadBoard / extractOBZ — File \| Blob \| ArrayBuffer \| ArrayBufferView | | UnzipLimits | Optional extraction caps — { maxEntrySize?, maxTotalOriginalSize?, maxEntries? } (see Security) | | UnzipOptions | Options for unzip / extractOBZ / loadOBZ / loadBoard — { limits?: UnzipLimits } | | 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, LoadedBoard, BinaryInput, UnzipLimits, and UnzipOptions 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

Every failure throws an OBFError. Branch on error.info.code — a discriminated union where each code carries exactly the fields relevant to that failure. Don't match on error.message; the message is human-readable and may change between releases.

import { loadBoard, OBFError } from "@shayc/open-board-format";

try {
  await loadBoard(file);
} catch (error) {
  if (!(error instanceof OBFError)) throw error;

  switch (error.info.code) {
    case "missing-resource":
      // `kind`, `mediaId`, and `path` are all typed and present here
      console.warn(`Missing ${error.info.kind} at ${error.info.path}`);
      break;
    case "invalid-board":
      // `issues` is the Zod issue list — which field failed and why
      console.error(error.info.issues);
      break;
    default:
      console.error(error.message);
  }
}

The code values, grouped by what they describe:

| Group | info.code | Key fields (on info) | | ----------- | ------------------- | --------------------------------------------- | | Decoding | not-json | source | | | not-zip | — | | | unreadable-zip | — | | | archive-too-large | limit, path, and the tripped cap's fields | | Validation | invalid-board | issues, boardId? | | | invalid-manifest | issues | | Read (OBZ) | missing-manifest | — | | | missing-board | boardId, path | | | board-id-mismatch | path, declaredId, actualId | | Write (OBZ) | unknown-root | rootBoardId | | | duplicate-board | boardId | | | missing-resource | kind, mediaId, path | | | conflicting-paths | kind, mediaId, paths | | | path-collision | path | | | zip-failed | — | | Internal | internal | detail |

OBFErrorInfo and OBFErrorCode are exported for exhaustive handling.

• The underlying error, when there is one, is always on the standard error.cause — never duplicated on info.
• Validation failures (invalid-board, invalid-manifest) put the ZodError on error.cause, so z.treeifyError(error.cause) gives nested, UI-friendly output, while info.issues (Zod's issue type, re-exported as OBFIssue) gives you the flat list directly.
• For not-json / *-zip failures, error.cause is the underlying parser or fflate error.
• An internal code signals a bug in this library that callers can't recover from — please report it.

Re-zipping an extracted .obz by hand? Zip the folder's contents, not the folder itself. If manifest.json ends up nested inside a top-level folder in the archive, extraction fails with missing-manifest even though the file is right there.

Security

OBZ archives are untrusted input. To guard against zip bombs, pass limits (via UnzipOptions) to loadBoard / loadOBZ / extractOBZ / unzip:

const parsed = await extractOBZ(buffer, {
  limits: {
    maxEntrySize: 100e6, // any single entry, in bytes
    maxTotalOriginalSize: 500e6, // sum of all entries, in bytes
    maxEntries: 10_000, // entry count, including directory entries
  },
});

Size limits are checked per entry against the uncompressed size declared in the archive's ZIP metadata, before that entry is inflated; maxEntries caps how many entries are processed at all. Entries accepted before a later entry trips a limit have already been inflated, but total allocation stays bounded by the caps. Exceeding a limit aborts extraction and rejects with an OBFError whose code is archive-too-large (info carries limit, the entry path that tripped it, and maxBytes/declaredBytes for the size limits or maxEntries/entryCount for the count). No limits are applied by default. A lying header can't force larger allocations — fflate allocates output buffers at exactly the declared size — so the declared-size caps bound memory use.

Entry paths are not sanitized — if you write extracted resources to disk, validate paths yourself first to avoid directory traversal.

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

Scope

What this library deliberately does not do:

• No network I/O — media referenced by url or data_url is not fetched; resolving external media is up to you.
• No rendering — it parses and validates data; drawing boards and playing sounds belong to your app.
• No default extraction limits, no path sanitization — size caps are opt-in via UnzipOptions; see Security before writing archive contents to disk.
• No referential integrity checks — a grid.order id with no matching button, or an image_id/sound_id with no matching image/sound, is not flagged. Resolving references is up to your rendering layer.

Versioning

Semver. The public API — every exported function, type, and Zod schema — is stable; breaking changes ship as major releases. 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. A 1:1 mirror is kept at docs/external/open-board-format.md for offline reference.
• 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