@conform-ed/contracts 0.0.8 → 0.0.9

package/h5p-v1-zod-templates.md

@@ -0,0 +1,124 @@
+# H5P v1 Zod Templates
+
+## Specification Sources
+
+| Source                      | URL                                                             |
+| --------------------------- | --------------------------------------------------------------- |
+| H5P Developer Specification | https://h5p.org/documentation/developers/h5p-specification      |
+| JSON File Descriptions      | https://h5p.org/documentation/developers/json-file-descriptions |
+| Semantics Reference         | https://h5p.org/documentation/developers/semantics              |
+| PHP Reference Library       | https://github.com/h5p/h5p-php-library                          |
+| NodeJS Reference Library    | https://github.com/Lumieducation/h5p-nodejs-library             |
+
+## Scope
+
+This bundle covers the four JSON schemas that make up the H5P package format:
+
+| File             | Schema                     | Description                                             |
+| ---------------- | -------------------------- | ------------------------------------------------------- |
+| `h5p.json`       | `H5pPackageManifestSchema` | Top-level package manifest in every `.h5p` archive      |
+| `library.json`   | `H5pLibraryManifestSchema` | Library directory manifest (runnable or helper library) |
+| `semantics.json` | `H5pSemanticsSchema`       | Editor form schema — array of typed field descriptors   |
+| `content.json`   | `H5pContentParamsSchema`   | Permissive base (`z.record`) for per-library content    |
+
+Not in scope: ZIP extraction, file whitelist checking, content validation against semantics.
+
+## Dependency Decision: Why No External Library
+
+| Library                            | Licence                          | Verdict                                                      |
+| ---------------------------------- | -------------------------------- | ------------------------------------------------------------ |
+| `h5p/h5p-php-library`              | GPL-3.0 (HTML purification code) | Cannot use — GPL is viral                                    |
+| `Lumieducation/h5p-nodejs-library` | MIT (JS parts)                   | Wrong abstraction — it's a full HTTP server, not a validator |
+
+We implement our own Zod schemas, referencing both libraries for validation logic and regex patterns.
+
+## Design Decisions
+
+### Machine name validation
+
+Pattern from `H5PValidator::isValidRequiredH5pData` in h5p-php-library:
+
+```
+/^[\w0-9\-\.]{1,255}$/i
+```
+
+Used on every `machineName` field and in the library folder name schema.
+
+### Patch version excluded from version references
+
+H5P dependency declarations (`preloadedDependencies`, `dynamicDependencies`, `editorDependencies`) use only `{ machineName, majorVersion, minorVersion }`. Any patch release of a matching major.minor is acceptable. `H5pVersionRefSchema` reflects this: it has no `patchVersion` field.
+
+`H5pLibraryManifestSchema` does include `patchVersion` because the library itself must declare its full three-part version.
+
+### `runnable` and `fullscreen` are integers, not booleans
+
+The H5P spec defines these as `0` or `1`, not `true`/`false`. `z.union([z.literal(0), z.literal(1)])` is used in `H5pLibraryManifestSchema` to match this exactly.
+
+### Semantics: recursive type handling
+
+`semantics.json` defines a recursive schema: `group` contains `fields: SemanticsField[]` and `list` contains `field: SemanticsField`. This is handled with the `z.lazy()` / let-then-assign pattern (same approach as cmi5 `Block`/`Au` schemas):
+
+```typescript
+let h5pSemanticsFieldSchemaInternal: z.ZodType<H5pSemanticsField>;
+
+const groupFieldSchema = z.object({
+  ...baseFieldShape,
+  type: z.literal("group"),
+  fields: z.lazy(() => z.array(h5pSemanticsFieldSchemaInternal)),
+  ...
+});
+
+h5pSemanticsFieldSchemaInternal = z.union([textFieldSchema, ..., groupFieldSchema, listFieldSchema]);
+```
+
+TypeScript-side recursive interfaces are declared manually to avoid circular inference, then the Zod schema is cast to `z.ZodType<H5pSemanticsField>`.
+
+### Semantics: non-strict objects
+
+Leaf field schemas (`textFieldSchema`, `numberFieldSchema`, etc.) use `z.object(...)` (not `strictObject()`) because:
+
+1. H5P has a large ecosystem of third-party widgets that add arbitrary extra properties to field definitions.
+2. The spec acknowledges extension properties on field objects.
+
+Only `H5pVersionRefSchema` and `H5pMediaFileSchema` use `strictObject()` since their shapes are fully specified.
+
+### Content params: permissive base
+
+`content.json` structure is defined per-library by its `semantics.json`. There is no universal content schema. `H5pContentParamsSchema` is `z.record(z.string(), z.unknown())` — structurally valid JSON objects.
+
+**Future work**: A `validateContentAgainstSemantics(content, semantics)` function could be built on top of `H5pSemanticsSchema` to perform deep structural validation. This requires a semantics traversal engine (walk the semantics field tree, validate each content value against its corresponding field schema). Out of scope for this bundle.
+
+### License codes
+
+Standard H5P license codes from the editor UI:
+`CC BY`, `CC BY-SA`, `CC BY-NC`, `CC BY-NC-SA`, `CC BY-ND`, `CC BY-NC-ND`, `CC0`, `GNU GPL`, `PD`, `ODC PDDL`, `CC PDM`, `U`
+
+`"U"` means undisclosed/unknown — the H5P default when no license is specified.
+
+## Validation Logic Derived from PHP Validator
+
+The following regex patterns are taken directly from `H5PValidator` in h5p-php-library:
+
+| Field           | Pattern                                            |
+| --------------- | -------------------------------------------------- |
+| `machineName`   | `/^[\w0-9\-\.]{1,255}$/i`                          |
+| `title`         | 1–255 characters                                   |
+| `language`      | `/^[-a-zA-Z]{1,10}$/` (ISO-639-1 + region subtags) |
+| version numbers | 1–5 digit integers                                 |
+| embed types     | only `"iframe"` or `"div"` allowed                 |
+
+Additional cross-field validations (implemented via `.superRefine()`):
+
+- `embedTypes` must not contain duplicates
+- `yearTo` must be ≥ `yearFrom` when both are present
+- Runnable iframe libraries without declared `w`/`h` emit a validation issue
+
+## File Whitelist (Not Validated by This Bundle)
+
+Per the H5P spec, only whitelisted file types are allowed in `.h5p` archives. This is a runtime/extraction concern rather than a JSON schema concern. For reference:
+
+**Content files**: `.png`, `.jpg`, `.jpeg`, `.gif`, `.bmp`, `.tif`, `.tiff`, `.svg`, `.mp3`, `.wav`, `.m4a`, `.mp4`, `.ogg`, `.webm`, `.pdf`, `.doc`, `.docx`, `.xls`, `.xlsx`, `.ppt`, `.pptx`, `.json`
+
+**Library files**: All of the above, plus `.js`, `.css`, `.xml`
+
+**Prohibited**: `.html`, `.htm`, any executable format

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@conform-ed/contracts",
-  "version": "0.0.8",
+  "version": "0.0.9",
   "type": "module",
   "module": "src/index.ts",
   "exports": {
@@ -27,7 +27,8 @@
     "./qti/v2_1": "./src/qti/v2_1/index.ts",
     "./qti/v2_2": "./src/qti/v2_2/index.ts",
     "./qti/v3_0_1": "./src/qti/v3_0_1/index.ts",
-    "./vc-data-model/v2_0": "./src/vc-data-model/v2_0/index.ts"
+    "./vc-data-model/v2_0": "./src/vc-data-model/v2_0/index.ts",
+    "./h5p/v1": "./src/h5p/v1/index.ts"
   },
   "scripts": {
     "build": "tsgo --noEmit",

package/src/h5p/v1/content.ts

@@ -0,0 +1,44 @@
+import { z } from "zod";
+import { strictObject } from "./shared";
+
+// Copyright information attached to media files in content.json.
+export const H5pCopyrightSchema = z.object({
+  license: z.string().optional(),
+  author: z.string().optional(),
+  year: z.string().optional(),
+  source: z.string().optional(),
+  title: z.string().optional(),
+  version: z.string().optional(),
+});
+
+// Media file reference as stored in content.json (image, audio, video, file fields).
+export const H5pMediaFileSchema = strictObject({
+  path: z.string().min(1),
+  mime: z.string(),
+  copyright: H5pCopyrightSchema.optional(),
+  // Original filename displayed in the editor
+  name: z.string().optional(),
+  // Width/height metadata for images
+  width: z.number().int().positive().optional(),
+  height: z.number().int().positive().optional(),
+});
+
+// Embedded H5P library reference as stored in content.json (library-type semantics fields).
+// The library string uses the format "H5P.MachineName majorVersion.minorVersion".
+export const H5pLibraryEmbedSchema = z.object({
+  library: z.string().regex(/^[\w0-9-.]+ \d+\.\d+$/u),
+  params: z.unknown(),
+  subContentId: z.string().optional(),
+  metadata: z.unknown().optional(),
+});
+
+// Base schema for any content.json document.
+// Content structure is defined per-library by semantics.json and therefore varies widely.
+// Full validation against semantics requires a semantics traversal engine — see notes in
+// h5p-v1-zod-templates.md for guidance on building one on top of H5pSemanticsSchema.
+export const H5pContentParamsSchema = z.record(z.string(), z.unknown());
+
+export type H5pCopyright = z.infer<typeof H5pCopyrightSchema>;
+export type H5pMediaFile = z.infer<typeof H5pMediaFileSchema>;
+export type H5pLibraryEmbed = z.infer<typeof H5pLibraryEmbedSchema>;
+export type H5pContentParams = z.infer<typeof H5pContentParamsSchema>;

package/src/h5p/v1/h5p-json.ts

@@ -0,0 +1,67 @@
+import { z } from "zod";
+import {
+  strictObject,
+  H5pMachineNameSchema,
+  H5pVersionRefSchema,
+  H5pLicenseSchema,
+  H5pAuthorSchema,
+  H5pChangelogEntrySchema,
+} from "./shared";
+
+// h5p.json — the top-level package manifest inside every .h5p archive.
+// Schema derived from H5PValidator::isValidRequiredH5pData in h5p-php-library.
+export const H5pPackageManifestSchema = strictObject({
+  // Required fields
+  title: z.string().min(1).max(255),
+  // ISO-639-1 language code with optional region subtag (e.g. "en", "nb", "zh-CN")
+  language: z.string().regex(/^[-a-zA-Z]{1,10}$/u),
+  machineName: H5pMachineNameSchema,
+  mainLibrary: H5pMachineNameSchema,
+  preloadedDependencies: z.array(H5pVersionRefSchema).min(1),
+  embedTypes: z.array(z.enum(["iframe", "div"])).min(1),
+
+  // Optional metadata
+  contentType: z.string().optional(),
+  description: z.string().optional(),
+  author: z.string().optional(),
+  authors: z.array(H5pAuthorSchema).optional(),
+  source: z.string().url().optional(),
+  license: H5pLicenseSchema.optional(),
+  licenseVersion: z.string().max(10).optional(),
+  licenseExtras: z.string().max(5000).optional(),
+  authorComments: z.string().max(5000).optional(),
+  dynamicDependencies: z.array(H5pVersionRefSchema).optional(),
+  // Fixed dimensions for non-responsive content — 1–4 digits per spec
+  width: z.number().int().min(1).max(9999).optional(),
+  height: z.number().int().min(1).max(9999).optional(),
+  metaKeywords: z.string().optional(),
+  metaDescription: z.string().optional(),
+  yearFrom: z.number().int().optional(),
+  yearTo: z.number().int().optional(),
+  defaultLanguage: z.string().max(32).optional(),
+  a11yTitle: z.string().max(255).optional(),
+  changes: z.array(H5pChangelogEntrySchema).optional(),
+}).superRefine((data, ctx) => {
+  // embedTypes must not have duplicates
+  const seen = new Set<string>();
+  for (const et of data.embedTypes) {
+    if (seen.has(et)) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["embedTypes"],
+        message: `Duplicate embed type: "${et}"`,
+      });
+    }
+    seen.add(et);
+  }
+  // yearTo must be >= yearFrom when both are present
+  if (data.yearFrom !== undefined && data.yearTo !== undefined && data.yearTo < data.yearFrom) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ["yearTo"],
+      message: "yearTo must be >= yearFrom",
+    });
+  }
+});
+
+export type H5pPackageManifest = z.infer<typeof H5pPackageManifestSchema>;

package/src/h5p/v1/index.ts

@@ -0,0 +1,109 @@
+export {
+  H5pMachineNameSchema,
+  H5pLibraryFolderNameSchema,
+  H5pVersionRefSchema,
+  H5pLicenseSchema,
+  H5pAuthorSchema,
+  H5pChangelogEntrySchema,
+} from "./shared";
+export type {
+  H5pMachineName,
+  H5pLibraryFolderName,
+  H5pVersionRef,
+  H5pLicense,
+  H5pAuthor,
+  H5pChangelogEntry,
+} from "./shared";
+
+export { H5pPackageManifestSchema } from "./h5p-json";
+export type { H5pPackageManifest } from "./h5p-json";
+
+export { H5pLibraryManifestSchema } from "./library-json";
+export type { H5pLibraryManifest } from "./library-json";
+
+export { H5pSemanticsFieldSchema, H5pSemanticsSchema } from "./semantics";
+export type {
+  H5pFieldBase,
+  H5pTextField,
+  H5pHtmlField,
+  H5pNumberField,
+  H5pBooleanField,
+  H5pImageField,
+  H5pAudioField,
+  H5pVideoField,
+  H5pFileField,
+  H5pSelectField,
+  H5pLibraryField,
+  H5pGroupField,
+  H5pListField,
+  H5pTableField,
+  H5pSemanticsField,
+  H5pSemantics,
+} from "./semantics";
+
+export { H5pCopyrightSchema, H5pMediaFileSchema, H5pLibraryEmbedSchema, H5pContentParamsSchema } from "./content";
+export type { H5pCopyright, H5pMediaFile, H5pLibraryEmbed, H5pContentParams } from "./content";
+
+import { H5pPackageManifestSchema } from "./h5p-json";
+import { H5pLibraryManifestSchema } from "./library-json";
+import { H5pSemanticsFieldSchema, H5pSemanticsSchema } from "./semantics";
+import { H5pCopyrightSchema, H5pMediaFileSchema, H5pLibraryEmbedSchema, H5pContentParamsSchema } from "./content";
+import {
+  H5pMachineNameSchema,
+  H5pLibraryFolderNameSchema,
+  H5pVersionRefSchema,
+  H5pLicenseSchema,
+  H5pAuthorSchema,
+  H5pChangelogEntrySchema,
+} from "./shared";
+
+export namespace H5pV1 {
+  export namespace Schemas {
+    export const PackageManifest = H5pPackageManifestSchema;
+    export const LibraryManifest = H5pLibraryManifestSchema;
+    export const SemanticsField = H5pSemanticsFieldSchema;
+    export const Semantics = H5pSemanticsSchema;
+    export const Copyright = H5pCopyrightSchema;
+    export const MediaFile = H5pMediaFileSchema;
+    export const LibraryEmbed = H5pLibraryEmbedSchema;
+    export const ContentParams = H5pContentParamsSchema;
+  }
+
+  export namespace Shared {
+    export const MachineName = H5pMachineNameSchema;
+    export const LibraryFolderName = H5pLibraryFolderNameSchema;
+    export const VersionRef = H5pVersionRefSchema;
+    export const License = H5pLicenseSchema;
+    export const Author = H5pAuthorSchema;
+    export const ChangelogEntry = H5pChangelogEntrySchema;
+  }
+}
+
+export type H5pV1Schemas = typeof H5pV1.Schemas;
+
+export const H5pV1DerivedZodTemplates = {
+  description: "H5P package and library Zod schemas for h5p.json, library.json, semantics.json, and content.json",
+  specLinks: {
+    specification: "https://h5p.org/documentation/developers/h5p-specification",
+    jsonFiles: "https://h5p.org/documentation/developers/json-file-descriptions",
+    semantics: "https://h5p.org/documentation/developers/semantics",
+    phpLibrary: "https://github.com/h5p/h5p-php-library",
+  },
+  scope:
+    "h5p.json (PackageManifest), library.json (LibraryManifest), semantics.json (SemanticsField array), content.json base types",
+  coreSchemas: ["H5pPackageManifestSchema", "H5pLibraryManifestSchema", "H5pSemanticsSchema"],
+  notes: [
+    "content.json structure varies per library — H5pContentParamsSchema is a permissive base (z.record). Full content validation requires semantics traversal.",
+    "Patch version intentionally excluded from H5pVersionRefSchema — any patch of the specified major.minor is acceptable per spec.",
+    "runnable and fullscreen are 0|1 integers, not booleans, matching the H5P spec.",
+    "PHP reference library (h5p-php-library) is GPL-3.0; NodeJS reference (Lumieducation/h5p-nodejs-library) is a full server framework. Neither is taken as a dependency.",
+    "Validation regex patterns for machineName and library folder names are derived from H5PValidator in h5p-php-library.",
+  ],
+} as const;
+
+export const DerivedZodTemplates = H5pV1DerivedZodTemplates;
+
+// Convenience aliases so that `H5pV1.Schemas.*` and `H5pV1.Shared.*` work
+// when consumers import via `export * as H5pV1 from "./h5p/v1"`.
+export const Schemas = H5pV1.Schemas;
+export const Shared = H5pV1.Shared;

package/src/h5p/v1/library-json.ts

@@ -0,0 +1,70 @@
+import { z } from "zod";
+import { strictObject, H5pMachineNameSchema, H5pVersionRefSchema } from "./shared";
+
+const filePathSchema = strictObject({ path: z.string().min(1) });
+
+const runnableFlag = z.union([z.literal(0), z.literal(1)]);
+
+// library.json — required in every H5P library directory.
+// Controls loading, dependencies, embedding, and editor capabilities.
+export const H5pLibraryManifestSchema = strictObject({
+  // Required fields
+  title: z.string().min(1),
+  machineName: H5pMachineNameSchema,
+  majorVersion: z.number().int().nonnegative().max(99999),
+  minorVersion: z.number().int().nonnegative().max(99999),
+  patchVersion: z.number().int().nonnegative().max(99999),
+  // 1 = standalone runnable content type, 0 = helper library only
+  runnable: runnableFlag,
+
+  // Optional fields
+  description: z.string().optional(),
+  author: z.string().optional(),
+  // library.json accepts any SPDX license string (e.g. "MIT", "Apache-2.0").
+  // Unlike h5p.json which restricts to H5P's enumerated content licenses.
+  license: z.string().max(32).optional(),
+
+  // JavaScript and CSS assets to preload
+  preloadedJs: z.array(filePathSchema).optional(),
+  preloadedCss: z.array(filePathSchema).optional(),
+
+  // Runtime dependencies (patch version excluded per spec)
+  preloadedDependencies: z.array(H5pVersionRefSchema).optional(),
+  // Loaded on-demand during execution
+  dynamicDependencies: z.array(H5pVersionRefSchema).optional(),
+  // Required only when the H5P editor is in use
+  editorDependencies: z.array(H5pVersionRefSchema).optional(),
+
+  // Embedding dimensions — required for iframe embed type
+  w: z.number().int().positive().optional(),
+  h: z.number().int().positive().optional(),
+  embedTypes: z.array(z.enum(["iframe", "div"])).optional(),
+  // 1 = supports fullscreen mode
+  fullscreen: runnableFlag.optional(),
+
+  contentType: z.string().optional(),
+
+  // Minimum H5P core API version this library requires
+  coreApi: strictObject({
+    majorVersion: z.number().int().nonnegative(),
+    minorVersion: z.number().int().nonnegative(),
+  }).optional(),
+
+  metadataSettings: strictObject({
+    disable: runnableFlag.optional(),
+    disableExtraTitleField: runnableFlag.optional(),
+  }).optional(),
+}).superRefine((data, ctx) => {
+  // iframe embedding requires explicit dimensions
+  if (data.runnable === 1 && data.embedTypes?.includes("iframe")) {
+    if (data.w === undefined || data.h === undefined) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["w"],
+        message: 'Runnable libraries with embedType "iframe" should declare w and h dimensions',
+      });
+    }
+  }
+});
+
+export type H5pLibraryManifest = z.infer<typeof H5pLibraryManifestSchema>;