@conform-ed/contracts 0.0.6 → 0.0.9

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>;

package/src/h5p/v1/semantics.ts

@@ -0,0 +1,268 @@
+import { z } from "zod";
+
+// Conditional visibility rule for a field — renders/hides based on another field's value.
+const showWhenRuleSchema = z.object({
+  field: z.string(),
+  equals: z.union([z.string(), z.boolean(), z.number(), z.array(z.string())]),
+});
+
+const showWhenSchema = z.object({
+  type: z.enum(["and", "or"]).optional(),
+  rules: z.array(showWhenRuleSchema),
+});
+
+// Shared optional base properties present on all field types.
+const baseFieldShape = {
+  name: z.string().min(1),
+  label: z.string().optional(),
+  description: z.string().optional(),
+  importance: z.enum(["high", "medium", "low"]).optional(),
+  optional: z.boolean().optional(),
+  common: z.boolean().optional(),
+  default: z.unknown().optional(),
+  widget: z.string().optional(),
+  showWhen: showWhenSchema.optional(),
+  // When field is hidden by showWhen, reset value to null
+  nullWhenHidden: z.boolean().optional(),
+  // Override default copy/paste behaviour in editor
+  copy: z.boolean().optional(),
+};
+
+// TypeScript-side recursive types must be declared manually to avoid circular inference.
+export interface H5pFieldBase {
+  name: string;
+  label?: string;
+  description?: string;
+  importance?: "high" | "medium" | "low";
+  optional?: boolean;
+  common?: boolean;
+  default?: unknown;
+  widget?: string;
+  showWhen?: { type?: "and" | "or"; rules: Array<{ field: string; equals: unknown }> };
+  nullWhenHidden?: boolean;
+  copy?: boolean;
+}
+
+export interface H5pTextField extends H5pFieldBase {
+  type: "text";
+  maxLength?: number;
+  minLength?: number;
+  regexp?: { pattern: string; modifiers?: string; description?: string };
+  placeholder?: string;
+  enterMode?: string;
+  tags?: string[];
+  font?: unknown;
+}
+export interface H5pHtmlField extends H5pFieldBase {
+  type: "html";
+  tags?: string[];
+  maxLength?: number;
+  minLength?: number;
+  placeholder?: string;
+  font?: unknown;
+}
+export interface H5pNumberField extends H5pFieldBase {
+  type: "number";
+  min?: number;
+  max?: number;
+  steps?: number;
+  decimals?: number;
+}
+export interface H5pBooleanField extends H5pFieldBase {
+  type: "boolean";
+}
+export interface H5pImageField extends H5pFieldBase {
+  type: "image";
+  allowedMimeTypes?: string[];
+  disableCopyright?: boolean;
+}
+export interface H5pAudioField extends H5pFieldBase {
+  type: "audio";
+  allowedMimeTypes?: string[];
+  disableConversion?: boolean;
+}
+export interface H5pVideoField extends H5pFieldBase {
+  type: "video";
+  allowedMimeTypes?: string[];
+  disableConversion?: boolean;
+}
+export interface H5pFileField extends H5pFieldBase {
+  type: "file";
+  allowedMimeTypes?: string[];
+}
+export interface H5pSelectField extends H5pFieldBase {
+  type: "select";
+  options: Array<{ value: string; label: string }>;
+  multiple?: boolean;
+}
+export interface H5pLibraryField extends H5pFieldBase {
+  type: "library";
+  options?: string[];
+}
+export interface H5pGroupField extends H5pFieldBase {
+  type: "group";
+  fields: H5pSemanticsField[];
+  isSubContent?: boolean;
+  expanded?: boolean;
+}
+export interface H5pListField extends H5pFieldBase {
+  type: "list";
+  field: H5pSemanticsField;
+  min?: number;
+  max?: number;
+  entity?: string;
+  widgets?: Array<{ name: string; label?: string }>;
+}
+export interface H5pTableField extends H5pFieldBase {
+  type: "table";
+  columns: H5pSemanticsField[];
+  rows?: number;
+}
+
+export type H5pSemanticsField =
+  | H5pTextField
+  | H5pHtmlField
+  | H5pNumberField
+  | H5pBooleanField
+  | H5pImageField
+  | H5pAudioField
+  | H5pVideoField
+  | H5pFileField
+  | H5pSelectField
+  | H5pLibraryField
+  | H5pGroupField
+  | H5pListField
+  | H5pTableField;
+
+// --- Zod schemas ---
+
+// Leaf field schemas (no recursion)
+const textFieldSchema = z.object({
+  ...baseFieldShape,
+  type: z.literal("text"),
+  maxLength: z.number().int().positive().optional(),
+  minLength: z.number().int().nonnegative().optional(),
+  regexp: z
+    .object({ pattern: z.string(), modifiers: z.string().optional(), description: z.string().optional() })
+    .optional(),
+  placeholder: z.string().optional(),
+  enterMode: z.string().optional(),
+  tags: z.array(z.string()).optional(),
+  font: z.unknown().optional(),
+});
+
+const htmlFieldSchema = z.object({
+  ...baseFieldShape,
+  type: z.literal("html"),
+  tags: z.array(z.string()).optional(),
+  maxLength: z.number().int().positive().optional(),
+  minLength: z.number().int().nonnegative().optional(),
+  placeholder: z.string().optional(),
+  font: z.unknown().optional(),
+});
+
+const numberFieldSchema = z.object({
+  ...baseFieldShape,
+  type: z.literal("number"),
+  min: z.number().optional(),
+  max: z.number().optional(),
+  steps: z.number().positive().optional(),
+  decimals: z.number().int().nonnegative().optional(),
+});
+
+const booleanFieldSchema = z.object({
+  ...baseFieldShape,
+  type: z.literal("boolean"),
+});
+
+const imageFieldSchema = z.object({
+  ...baseFieldShape,
+  type: z.literal("image"),
+  allowedMimeTypes: z.array(z.string()).optional(),
+  disableCopyright: z.boolean().optional(),
+});
+
+const audioFieldSchema = z.object({
+  ...baseFieldShape,
+  type: z.literal("audio"),
+  allowedMimeTypes: z.array(z.string()).optional(),
+  disableConversion: z.boolean().optional(),
+});
+
+const videoFieldSchema = z.object({
+  ...baseFieldShape,
+  type: z.literal("video"),
+  allowedMimeTypes: z.array(z.string()).optional(),
+  disableConversion: z.boolean().optional(),
+});
+
+const fileFieldSchema = z.object({
+  ...baseFieldShape,
+  type: z.literal("file"),
+  allowedMimeTypes: z.array(z.string()).optional(),
+});
+
+const selectFieldSchema = z.object({
+  ...baseFieldShape,
+  type: z.literal("select"),
+  options: z.array(z.object({ value: z.string(), label: z.string() })),
+  multiple: z.boolean().optional(),
+});
+
+const libraryFieldSchema = z.object({
+  ...baseFieldShape,
+  type: z.literal("library"),
+  options: z.array(z.string()).optional(),
+});
+
+// Recursive field schemas — use z.lazy so they can reference the outer union.
+// Using let-then-assign pattern (same as cmi5 Block/Au schemas).
+let h5pSemanticsFieldSchemaInternal: z.ZodType<H5pSemanticsField>;
+
+const groupFieldSchema: z.ZodType<H5pGroupField> = z.object({
+  ...baseFieldShape,
+  type: z.literal("group"),
+  fields: z.lazy(() => z.array(h5pSemanticsFieldSchemaInternal)),
+  isSubContent: z.boolean().optional(),
+  expanded: z.boolean().optional(),
+}) as z.ZodType<H5pGroupField>;
+
+const listFieldSchema: z.ZodType<H5pListField> = z.object({
+  ...baseFieldShape,
+  type: z.literal("list"),
+  field: z.lazy(() => h5pSemanticsFieldSchemaInternal),
+  min: z.number().int().nonnegative().optional(),
+  max: z.number().int().positive().optional(),
+  entity: z.string().optional(),
+  widgets: z.array(z.object({ name: z.string(), label: z.string().optional() })).optional(),
+}) as z.ZodType<H5pListField>;
+
+const tableFieldSchema: z.ZodType<H5pTableField> = z.object({
+  ...baseFieldShape,
+  type: z.literal("table"),
+  columns: z.lazy(() => z.array(h5pSemanticsFieldSchemaInternal)),
+  rows: z.number().int().positive().optional(),
+}) as z.ZodType<H5pTableField>;
+
+h5pSemanticsFieldSchemaInternal = z.union([
+  textFieldSchema,
+  htmlFieldSchema,
+  numberFieldSchema,
+  booleanFieldSchema,
+  imageFieldSchema,
+  audioFieldSchema,
+  videoFieldSchema,
+  fileFieldSchema,
+  selectFieldSchema,
+  libraryFieldSchema,
+  groupFieldSchema,
+  listFieldSchema,
+  tableFieldSchema,
+]) as z.ZodType<H5pSemanticsField>;
+
+// The schema for a single semantics field (any type).
+export const H5pSemanticsFieldSchema: z.ZodType<H5pSemanticsField> = h5pSemanticsFieldSchemaInternal;
+
+// The top-level semantics.json document — an array of field definitions.
+export const H5pSemanticsSchema = z.array(H5pSemanticsFieldSchema);
+export type H5pSemantics = z.infer<typeof H5pSemanticsSchema>;

package/src/h5p/v1/shared.ts

@@ -0,0 +1,56 @@
+import { z } from "zod";
+
+export function strictObject<T extends z.ZodRawShape>(shape: T) {
+  return z.object(shape).strict();
+}
+
+// Machine name: alphanumeric, hyphens, dots — used in machineName fields and folder names.
+// Pattern from h5p-php-library H5PValidator::isValidRequiredH5pData
+export const H5pMachineNameSchema = z.string().regex(/^[\w0-9-.]{1,255}$/iu);
+
+// Library folder name without patch: "H5P.Image-1.1", "H5P.Column-1.22"
+// Patch version is intentionally excluded from folder names and dependency references per spec.
+export const H5pLibraryFolderNameSchema = z.string().regex(/^[\w0-9-.]{1,255}-\d{1,5}\.\d{1,5}$/u);
+
+// Version reference used in preloadedDependencies / dynamicDependencies / editorDependencies.
+// Patch is intentionally omitted — any patch of the specified major.minor is acceptable.
+export const H5pVersionRefSchema = strictObject({
+  machineName: H5pMachineNameSchema,
+  majorVersion: z.number().int().nonnegative().max(99999),
+  minorVersion: z.number().int().nonnegative().max(99999),
+});
+
+// Standard H5P license codes as used in h5p.json and library.json.
+// "U" = undisclosed/unknown (H5P default when no license is specified).
+export const H5pLicenseSchema = z.enum([
+  "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",
+]);
+
+export const H5pAuthorSchema = strictObject({
+  name: z.string().min(1),
+  role: z.string().optional(),
+});
+
+export const H5pChangelogEntrySchema = strictObject({
+  date: z.string(),
+  changes: z.array(z.string()),
+});
+
+// Inferred types
+export type H5pMachineName = z.infer<typeof H5pMachineNameSchema>;
+export type H5pLibraryFolderName = z.infer<typeof H5pLibraryFolderNameSchema>;
+export type H5pVersionRef = z.infer<typeof H5pVersionRefSchema>;
+export type H5pLicense = z.infer<typeof H5pLicenseSchema>;
+export type H5pAuthor = z.infer<typeof H5pAuthorSchema>;
+export type H5pChangelogEntry = z.infer<typeof H5pChangelogEntrySchema>;

package/src/index.ts

@@ -30,3 +30,5 @@ export * as ClrV2_0 from "./clr/v2_0";
 export * as OpenBadgesV3_0 from "./open-badges/v3_0";
 export * as OneRosterV1_2 from "./oneroster/v1_2";
 export * as VcDataModelV2_0 from "./vc-data-model/v2_0";
+export * as H5pV1 from "./h5p/v1";
+export { H5pV1DerivedZodTemplates } from "./h5p/v1";

package/src/lti/ags/v2_0/index.ts

@@ -29,7 +29,7 @@ export const LineItemSchema = strictObject({
   gradesReleased: z.boolean().optional(),
 });
 
-export const ScoreProgressSchema = z.enum(["Completed", "Failed", "InProgress", "Initialized", "Submitted", "Started"]);
+export const ScoreProgressSchema = z.enum(["Completed", "InProgress", "Initialized", "Submitted", "Started"]);
 export const GradingProgressSchema = z.enum(["Failed", "FullyGraded", "NotReady", "Pending", "PendingManual"]);
 
 export const ScoreSubmissionSchema = strictObject({

package/src/xapi/shared.ts

@@ -53,7 +53,8 @@ export const AgentSchema = strictObject({
   if (ifiCount !== 1) {
     ctx.addIssue({
       code: z.ZodIssueCode.custom,
-      message: "An xAPI Agent requires exactly one Inverse Functional Identifier (mbox, mbox_sha1sum, openid, or account)",
+      message:
+        "An xAPI Agent requires exactly one Inverse Functional Identifier (mbox, mbox_sha1sum, openid, or account)",
     });
   }
 });
@@ -241,6 +242,7 @@ export const AttachmentSchema = strictObject({
   length: z.number().int().nonnegative(),
   sha2: AttachmentSha2Schema,
   fileUrl: z.url().optional(),
+  contentBase64: z.string().optional(),
 });
 
 export const XapiDocumentSchema = strictObject({