Skip to content

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

Merged
alekswebnet merged 3 commits into
mainfrom
feat/source-schema
Nov 18, 2026
Merged

alekswebnet merged 3 commits into
mainfrom
feat/source-schema

Conversation

@alekswebnet

@alekswebnet alekswebnet commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

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 (h5p-author: a chat with no skill text spends a round on each layer of a source's outer shape #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 feat(mcp): a local MCP server that builds, checks and previews packages #227's server with this schema shown (built locally, not pushed). The tasks were the ones feat(mcp): a local MCP server that builds, checks and previews packages #227 was tested with: a quiz with volcano.png, a Course Presentation, and an Interactive Video from clip.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_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 feat(mcp): a local MCP server that builds, checks and previews packages #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

Written for commit f64fda4. Summary will update on new commits.

View guided diff Turn on auto-fix

sourceSchema, in zod/mini, is a source's own fields: sourceOf holds each field to it and says its
message where the field was written, the Source type is its output, and it is exported, so that a
model can be shown the shape of a source before writing one. What one field cannot say alone stays
in sourceOf: 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. The messages are as they were, but every
problem of an author is now said at once, and an author written as a name alone is said with the
object to write, as Haiku wrote one through the MCP server. zod/mini adds 23 kB minified to a build
in a page, where zod's chained API would add 93 kB.
@socket-security

socket-security Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff Package Supply Chain
Security
Vulnerability Quality Maintenance License
Addedzod@​4.6.710010010091100

View full report

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All reported issues were addressed across 9 files

Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic

Comment thread packages/author/README.md Resolved
Comment thread design/author.md Resolved
Comment thread packages/author/lib/source-schema.mjs Resolved
… an empty one (#230)

A schema shown with "params": { "default": {} } had Haiku send an empty params three times in
one Interactive Video run, though a build refused each. params is optional, as a build takes it,
with no default said, and the Source type has it optional too.
…he caller's own (#230)

What cubic found: build.mjs kept its own list of a source's fields beside the schema, so it now
takes them from sourceSchema.shape, and the messages for a field no source has and for a source
that is no object are said in one place. sourceSchema refuses a field no source has, as a build
does, where it dropped one; an app is shown that too. The README says that toJSONSchema comes from
a zod of the caller's own, 4.2 or later, since pnpm does not let a package import the author
package's copy.
@alekswebnet
alekswebnet merged commit d458ae4 into main Nov 18, 2026
14 checks passed
@alekswebnet
alekswebnet deleted the feat/source-schema branch November 18, 2026 11:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

author: declare a source's own fields once, as a schema a model can be shown

1 participant