Inspect and validate
Two commands answer questions about a course without producing output you then have to throw away.
oaf inspect— what is in this file?oaf validate— does it produce a conformant OAF package?
Both work by running the same .story conversion the other commands use, so
either one also tells you whether a file can be read at all.
Inspecting
oaf inspect my-course.story
The default tree format prints the scene and slide hierarchy — enough to see
the shape of a course in one screen.
More detail
oaf inspect my-course.story --slides --quizzes --media
| Flag | Adds |
|---|---|
--slides | Per-slide detail |
--quizzes | Every quiz question |
--media | Every media file |
Other output formats
oaf inspect my-course.story --format summary
oaf inspect my-course.story --format json
summary gives counts and headline metadata. json prints the entire OAF
package to stdout, which is the one to reach for when you want to query it:
oaf inspect my-course.story --format json | jq '.slides | length'
oaf inspect my-course.story --format json | jq -r '.media[].path'
This is the most direct way to see exactly what the converter produced, without going through a writer that may drop things.
Validating
oaf validate my-course.story
Validation runs in two stages, and it is worth knowing which one failed.
Conversion warnings come first — things in the source the converter could not represent. These do not make the package invalid.
Schema validation comes second, checking the package against the JSON
Schemas in @oaf/spec. Failures here are structural: a missing required field,
a bad path, an unrecognized property.
Because the schemas set additionalProperties: false, a field the spec does not
know about is an error rather than something quietly passed through. That is
deliberate — it catches a converter emitting a field nothing downstream will
read.
Strict mode
oaf validate my-course.story --strict
Off by default.
When to use which
Reach for inspect when you want to understand a file — before converting,
or when output is missing something and you need to know whether it was lost on
the way in or on the way out. Converting to JSON and inspecting the package
settles that question directly.
Reach for validate when you are extending the toolchain — writing a converter,
or changing one — and need to know the package you produced actually conforms.