feat(author): declare a source's own fields once, as a schema (#230)
Closes #230.
sourceSchema declares a source's own fields once, in zod/mini, in lib/source-schema.mjs. The author package exports it from all three entries, through ./core.
What changes
sourceOftakes its list of fields from the schema and holds each field to it. Each problem is said where the field was written. The schema rejects any field a source may not have, as a build does, with the build's message, and an app is shownadditionalProperties: false. What one field can't say alone stays in code: a content type named loosely, a licence written with its version, a version for a licence that takes none, and fields in the wrong place (#174).- Messages are unchanged, with two exceptions:
- every problem of an author is now said at once, where the build used to say only the first;
- an author written as a name alone gets the object to write:
authors[0]: expected an author: write { "name": "Unknown", "role": "Author" }. It used to getauthors[0].name: expected the author's name. Haiku wroteauthors: ["Unknown"]through the MCP server.
Sourceis the schema's output type, in place of the hand-written typedef.paramsis optional in it, as a build takes it. The schema states no default forparams: when it showed"default": {}, one Haiku run sent an emptyparamsthree times.- zod/mini, not zod, because a build runs in a page too. Measured with esbuild, the schema adds 23.2 kB minified (7.6 kB gzipped) with zod/mini, against 92.6 kB (26.9 kB gzipped) with zod's chained API. JSON Schema is made where it's shown, so a build in a page doesn't carry the converter.
- Docs: the rule in
design/author.md. The README covers the export andtoJSONSchema, which needs a zod of the caller's own, 4.2 or later: pnpm won't let them import the author package's copy.
Testing
-
Author: 222 tests pass, the browser project included. Every existing message test passes unchanged. The new test covers:
- an author written as a name alone;
- every problem of one author at once;
- the schema as JSON Schema: the fields a source must name, the licence codes, and an author's two fields.
-
Types:
tscpasses, andpackage-types.tspinssourceSchema, whose output is aSource. -
Haiku 5.5 in Claude Code, through #227's server with this schema shown (built locally, not pushed). The tasks were the ones #227 was tested with: a quiz with
volcano.png, a Course Presentation, and an Interactive Video fromclip.mp4.Server Runs that built First build wrote "authors": ["Unknown"]without the schema 3 2 with it 6 0 Every other refusal, with or without the schema, was about the content.
Not here
- The MCP server's use of it.
h5p_buildshows this schema for itssource, as JSON Schema metadata on a field that still takes any object, so the SDK never refuses a source before the build has listed every problem. The commit is ready, four files with tests, and lands with whichever of #227 and this PR merges second. - The organisation's site. Its one-file CLI and build page will carry zod/mini (MIT) at their next pin, so their licence notices need it added.
Summary by cubic
Declares a source's own fields once as sourceSchema in zod/mini, exported from the author package, and holds each field of a source to it in sourceOf. The schema is strict, so it refuses a field no source has, and the build takes its field list from the schema's shape, keeping one list.
- The
Sourcetype is now the schema's output type, replacing the hand-written typedef. - Every problem of an author is reported at once instead of only the first.
- An author written as a name alone now gets the object to write, e.g.
authors[0]: expected an author: write { "name": "Unknown", "role": "Author" }. paramsis shown as optional with no default so the schema no longer suggests sending an emptyparams.- Uses
zod/minibecause builds run in a page too: it adds 23.2 kB minified (7.6 kB gzipped) against 92.6 kB (26.9 kB gzipped) for zod's chained API. - Adds the
zoddependency and documentssourceSchemain the README anddesign/author.md; the README notestoJSONSchemaneeds a zod of the caller's own, 4.2 or later.
Not here
- The MCP server's use of the schema lands with whichever of #227 and this PR merges second.
- The organisation's site will need
zod/mini(MIT) added to its licence notices at its next pin.