feat(author): declare a source's own fields once, as a schema (#230)

Merged
AL
10h ago
+191-71

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

  • sourceOf takes 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 shown additionalProperties: 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 get authors[0].name: expected the author's name. Haiku wrote authors: ["Unknown"] through the MCP server.
  • Source is the schema's output type, in place of the hand-written typedef. params is optional in it, as a build takes it. The schema states no default for params: when it showed "default": {}, one Haiku run sent an empty params three 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 and toJSONSchema, 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: tsc passes, and package-types.ts pins sourceSchema, whose output is a Source.

  • 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 from clip.mp4.

    ServerRuns that builtFirst build wrote "authors": ["Unknown"]
    without the schema32
    with it60

    Every other refusal, with or without the schema, was about the content.

Not here

  • The MCP server's use of it. h5p_build shows this schema for its source, 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 Source type 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" }.
  • params is shown as optional with no default so the schema no longer suggests sending an empty params.
  • Uses zod/mini because 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 zod dependency and documents sourceSchema in the README and design/author.md; the README notes toJSONSchema needs 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.