Schema package
@audioguidekit/schema on npm: types, JSON Schemas, manifest validation and editor field descriptions for tools that write AudioGuideKit content
@audioguidekit/schema is the data contract of the player, published on npm. It describes exactly what a tour, an app.json and a manifest may contain, and checks that a file follows the rules.
You don't need it to run the player. The player already has it inside. You need it when you build something that writes content for the player: an editor, a CMS export, a script that turns a spreadsheet into tours, or a check in your own build.
Install
npm install @audioguidekit/schemaWith Bun it is bun add @audioguidekit/schema.
It is an ES module and runs in Node 20.10 or later, in Bun, or in any bundler. The source lives in the player repo, in packages/schema.
Check a manifest before you publish it
import { validateManifest, type Manifest } from '@audioguidekit/schema';
const result = validateManifest(manifest);
if (!result.valid) {
console.error(result.errors);
}Every error starts with the path to the problem, such as tours[0].languages.en.stops[3]: …, so you know which stop to fix.
validateManifest checks three things, in this order:
schemaVersion: a manifest written for another version of the format is refused straight away, because the player would refuse it too.- The JSON Schema: unknown properties, wrong values, missing required fields.
- Rules a schema cannot express: tour ids that match across files, no duplicate ids, themes that exist, and
totalStopsequal to the number of audio stops.
For single files there are validateTourFile (a language file like en.json), validateTourMetadata (metadata.json) and validateAppConfig (app.json).
Run the check in the step that publishes the manifest. A file that fails it would show an error screen in the player instead of your tour.
What is inside
- Types for the manifest, tours, language files,
app.json, every stop type, themes and interface texts:Manifest,ManifestTour,TourFile,TourMetadataFile,AppConfigFile,ThemeConfig,CustomTheme,UiTextand more. - JSON Schemas for a language file,
metadata.json,app.jsonand the manifest. You get them asjsonSchemasfrom the package, or as files:@audioguidekit/schema/schemas/manifest.schema.json(alsotour-file,tour-metadataandapp-config). - Field descriptions, for building an editor (below).
SCHEMA_VERSION, the version of the manifest format that this release of the package understands.
Build an editor from the field descriptions
import { FIELD_CATALOG, STOP_TYPES } from '@audioguidekit/schema/fields';For every field the schemas accept, the package says how to show it in a form: label, group, kind of control, default, options and help text. STOP_TYPES lists them per stop type. FIELD_CATALOG puts every field in one list, each with a scope: a stop type, the tour (content, settings, map), app, a custom theme or ui (interface texts).
So when the player gets a new setting, an editor built on the catalog shows it after a package update, with no new form code.
Check JSON files in your code editor
Point the $schema key of a file at the schema on a CDN, and VS Code and most other editors underline mistakes while you type:
{
"$schema": "https://unpkg.com/@audioguidekit/schema@1/dist/schemas/tour-file.schema.json",
"id": "barcelona",
"language": "en"
}Inside the player repo the files already point at local copies, so you don't need this there.
Versions
The package follows semver. A change that would break existing manifests raises SCHEMA_VERSION and is a new major version of the package. Everything else (new optional fields, new stop types, better help texts) comes in minor and patch versions, so ^1 is safe to depend on.
The package has its own version numbers, separate from the player's. New versions are listed on Updates and on npm.
Related
- Manifest mode: the format the package validates, and how the player loads it.
- Stop types: what each stop type looks like in a tour file.