@conform-ed/contracts 0.0.3

package/test/vc-data-model-v2_0.test.ts

@@ -0,0 +1,63 @@
+import { expect, test } from "bun:test";
+
+import { VcDataModelV2_0 } from "../src";
+
+test("VerifiableCredentialSchema parses a minimal VC Data Model 2.0 credential", () => {
+  const parsed = VcDataModelV2_0.VerifiableCredentialSchema.safeParse({
+    "@context": ["https://www.w3.org/ns/credentials/v2"],
+    type: "VerifiableCredential",
+    issuer: "https://example.test/issuers/1",
+    validFrom: "2025-01-01T00:00:00Z",
+    credentialSubject: {
+      id: "did:example:subject-1",
+    },
+  });
+
+  expect(parsed.success).toBe(true);
+});
+
+test("VerifiablePresentationSchema parses a presentation carrying VC and JWS credentials", () => {
+  const parsed = VcDataModelV2_0.VerifiablePresentationSchema.safeParse({
+    "@context": ["https://www.w3.org/ns/credentials/v2"],
+    type: "VerifiablePresentation",
+    holder: "did:example:holder-1",
+    verifiableCredential: [
+      {
+        "@context": ["https://www.w3.org/ns/credentials/v2"],
+        type: "VerifiableCredential",
+        issuer: "https://example.test/issuers/1",
+        validFrom: "2025-01-01T00:00:00Z",
+        credentialSubject: {
+          id: "did:example:subject-1",
+        },
+      },
+      "header.payload.signature",
+    ],
+  });
+
+  expect(parsed.success).toBe(true);
+});
+
+test("VerifiableCredentialSchema rejects wrong core context", () => {
+  const parsed = VcDataModelV2_0.VerifiableCredentialSchema.safeParse({
+    "@context": ["https://example.test/context"],
+    type: "VerifiableCredential",
+    issuer: "https://example.test/issuers/1",
+    validFrom: "2025-01-01T00:00:00Z",
+    credentialSubject: {
+      id: "did:example:subject-1",
+    },
+  });
+
+  expect(parsed.success).toBe(false);
+});
+
+test("VcDataModel20DerivedZodTemplates exposes expected entry points", () => {
+  expect(VcDataModelV2_0.VcDataModel20DerivedZodTemplates.verifiableCredential).toBe(
+    VcDataModelV2_0.VerifiableCredentialSchema,
+  );
+  expect(VcDataModelV2_0.VcDataModel20DerivedZodTemplates.verifiablePresentation).toBe(
+    VcDataModelV2_0.VerifiablePresentationSchema,
+  );
+  expect(VcDataModelV2_0.VcDataModel20DerivedZodTemplates.proof).toBe(VcDataModelV2_0.ProofSchema);
+});

package/test/xapi.test.ts

@@ -0,0 +1,384 @@
+import { expect, test } from "bun:test";
+import { XapiV1_0_3, XapiV2_0 } from "@conform-ed/contracts";
+
+const attachmentSha2 = "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef";
+
+const validStatement = {
+  actor: {
+    objectType: "Agent",
+    mbox: "mailto:alice@example.com",
+    name: "Alice",
+  },
+  verb: {
+    id: "http://adlnet.gov/expapi/verbs/completed",
+    display: { "en-US": "completed" },
+  },
+  object: {
+    objectType: "Activity",
+    id: "http://example.com/activities/course-1",
+    definition: {
+      name: { "en-US": "Course 1" },
+      description: { "en-US": "Example course" },
+      interactionType: "choice",
+      correctResponsesPattern: ["a"],
+      choices: [{ id: "a", description: { "en-US": "Choice A" } }],
+    },
+  },
+  result: {
+    score: { scaled: 1, raw: 100, min: 0, max: 100 },
+    success: true,
+    completion: true,
+    duration: "PT1H",
+  },
+  context: {
+    registration: "550e8400-e29b-41d4-a716-446655440000",
+    platform: "conform-ed",
+    language: "en-US",
+    contextActivities: {
+      parent: [{ id: "http://example.com/activities/course-1" }],
+    },
+  },
+  timestamp: "2026-05-28T12:00:00.000Z",
+  version: "1.0.3",
+} as const;
+
+test("xAPI 1.0.3 statement schema accepts the core data model", () => {
+  expect(XapiV1_0_3.Schemas.Statement.safeParse(validStatement).success).toBe(true);
+});
+
+test("xAPI 2.0 statement schema accepts the same core data model", () => {
+  expect(
+    XapiV2_0.Schemas.Statement.safeParse({
+      ...validStatement,
+      version: "2.0",
+    }).success,
+  ).toBe(true);
+});
+
+test("xAPI 2.0 statement schema accepts IEEE 2.0 contextAgent/contextGroup objects", () => {
+  const statementV2 = {
+    ...validStatement,
+    version: "2.0",
+    context: {
+      ...validStatement.context,
+      contextAgents: [
+        {
+          objectType: "contextAgent",
+          agent: {
+            objectType: "Agent",
+            mbox: "mailto:observer@example.com",
+          },
+          relevantTypes: ["https://example.com/xapi/relevant-types/observer"],
+        },
+      ],
+      contextGroups: [
+        {
+          objectType: "contextGroup",
+          group: {
+            objectType: "Group",
+            account: {
+              homePage: "https://example.com/groups",
+              name: "cohort-7",
+            },
+          },
+          relevantTypes: ["https://example.com/xapi/relevant-types/cohort"],
+        },
+      ],
+    },
+  } as const;
+
+  expect(XapiV2_0.Schemas.Statement.safeParse(statementV2).success).toBe(true);
+  expect(XapiV2_0.Schemas.StatementSubmission.safeParse([statementV2]).success).toBe(true);
+  expect(
+    XapiV2_0.Schemas.StatementResult.safeParse({
+      statements: [statementV2],
+      more: "/xapi/statements?more=page-2",
+    }).success,
+  ).toBe(true);
+  expect(
+    XapiV2_0.Schemas.MultipartRequest.safeParse({
+      contentType: "multipart/mixed",
+      parts: [
+        {
+          contentType: "application/json",
+          body: statementV2,
+        },
+        [
+          {
+            headers: {
+              "Content-Type": "application/json",
+              "Content-Transfer-Encoding": "binary",
+              "X-Experience-API-Hash": attachmentSha2,
+            },
+            body: new Uint8Array([0x7b, 0x7d]),
+          },
+        ],
+      ],
+    }).success,
+  ).toBe(true);
+
+  expect(XapiV1_0_3.Schemas.Statement.safeParse(statementV2).success).toBe(false);
+});
+
+test("xAPI statement submission schema accepts batches", () => {
+  expect(XapiV1_0_3.Schemas.StatementSubmission.safeParse([validStatement]).success).toBe(true);
+});
+
+test("xAPI document, listing, and about schemas validate LRS metadata", () => {
+  expect(
+    XapiV1_0_3.Schemas.AboutResource.safeParse({
+      version: ["1.0.3"],
+      extensions: {
+        "https://example.com/xapi/lrs/extensions/features": ["person", "statement-result"],
+      },
+    }).success,
+  ).toBe(true);
+
+  expect(
+    XapiV1_0_3.Schemas.StateDocumentQuery.safeParse({
+      activityId: "http://example.com/activities/course-1",
+      agent: { mbox: "mailto:alice@example.com" },
+      registration: "550e8400-e29b-41d4-a716-446655440000",
+      stateId: "progress",
+    }).success,
+  ).toBe(true);
+
+  expect(
+    XapiV1_0_3.Schemas.XapiDocument.safeParse({
+      contentType: "application/json",
+      body: { progress: 0.5 },
+      etag: '"abc123"',
+      lastModified: "2026-05-28T12:00:00.000Z",
+    }).success,
+  ).toBe(true);
+
+  expect(
+    XapiV1_0_3.Schemas.StateDocumentListingQuery.safeParse({
+      activityId: "http://example.com/activities/course-1",
+      agent: { mbox: "mailto:alice@example.com" },
+      since: "2026-05-27T12:00:00.000Z",
+    }).success,
+  ).toBe(true);
+
+  expect(
+    XapiV1_0_3.Schemas.AgentProfileDocumentListingQuery.safeParse({
+      agent: { mbox: "mailto:alice@example.com" },
+      since: "2026-05-27T12:00:00.000Z",
+    }).success,
+  ).toBe(true);
+
+  expect(
+    XapiV1_0_3.Schemas.ActivityProfileDocumentListingQuery.safeParse({
+      activityId: "http://example.com/activities/course-1",
+      since: "2026-05-27T12:00:00.000Z",
+    }).success,
+  ).toBe(true);
+
+  expect(XapiV1_0_3.Schemas.XapiDocumentIdList.safeParse(["bookmark", "progress"]).success).toBe(true);
+});
+
+test("xAPI validation rejects statements missing required fields", () => {
+  expect(
+    XapiV1_0_3.Schemas.Statement.safeParse({
+      verb: { id: "http://adlnet.gov/expapi/verbs/completed" },
+      object: { id: "http://example.com/activities/course-1" },
+    }).success,
+  ).toBe(false);
+});
+
+test("xAPI statement result, person object, and resource queries validate missing spec objects", () => {
+  expect(
+    XapiV1_0_3.Schemas.StatementResult.safeParse({
+      statements: [validStatement],
+      more: "/xapi/statements?more=opaque-token",
+    }).success,
+  ).toBe(true);
+
+  expect(
+    XapiV1_0_3.Schemas.StatementResult.safeParse({
+      statements: [validStatement],
+      more: "https://example.com/xapi/statements?more=absolute",
+    }).success,
+  ).toBe(false);
+
+  expect(
+    XapiV1_0_3.Schemas.Person.safeParse({
+      objectType: "Person",
+      name: ["Alice Example"],
+      mbox: ["mailto:alice@example.com"],
+      account: [
+        {
+          homePage: "https://example.com/accounts",
+          name: "alice",
+        },
+      ],
+    }).success,
+  ).toBe(true);
+
+  expect(
+    XapiV1_0_3.Schemas.AgentsResourceQuery.safeParse({
+      agent: { mbox: "mailto:alice@example.com" },
+    }).success,
+  ).toBe(true);
+
+  expect(
+    XapiV1_0_3.Schemas.ActivitiesResourceQuery.safeParse({
+      activityId: "http://example.com/activities/course-1",
+    }).success,
+  ).toBe(true);
+
+  expect(
+    XapiV1_0_3.Schemas.StatementsQuery.safeParse({
+      agent: { mbox: "mailto:alice@example.com" },
+      verb: "http://adlnet.gov/expapi/verbs/completed",
+      since: "2026-05-27T12:00:00.000Z",
+      format: "canonical",
+      attachments: true,
+      ascending: false,
+    }).success,
+  ).toBe(true);
+});
+
+// LRS/Content schema tests
+test("xAPI HTTP method enum validates LRS operations", () => {
+  expect(XapiV1_0_3.Schemas.HttpMethod.safeParse("GET").success).toBe(true);
+  expect(XapiV1_0_3.Schemas.HttpMethod.safeParse("POST").success).toBe(true);
+  expect(XapiV1_0_3.Schemas.HttpMethod.safeParse("PUT").success).toBe(true);
+  expect(XapiV1_0_3.Schemas.HttpMethod.safeParse("DELETE").success).toBe(true);
+  expect(XapiV1_0_3.Schemas.HttpMethod.safeParse("PATCH").success).toBe(false);
+});
+
+test("xAPI error response schema validates LRS error payloads", () => {
+  expect(
+    XapiV1_0_3.Schemas.ErrorResponse.safeParse({
+      code: "400",
+      message: "Invalid request",
+      details: "Missing required field: actor",
+    }).success,
+  ).toBe(true);
+
+  expect(
+    XapiV1_0_3.Schemas.ErrorResponse.safeParse({
+      code: "500",
+      message: "Internal server error",
+    }).success,
+  ).toBe(true);
+
+  expect(
+    XapiV1_0_3.Schemas.ErrorResponse.safeParse({
+      code: "400",
+      message: "Invalid request",
+      extra: "should not be here",
+    }).success,
+  ).toBe(false);
+});
+
+test("xAPI error codes validate standard HTTP status responses", () => {
+  expect(XapiV1_0_3.Schemas.ErrorCode.safeParse("400").success).toBe(true);
+  expect(XapiV1_0_3.Schemas.ErrorCode.safeParse("401").success).toBe(true);
+  expect(XapiV1_0_3.Schemas.ErrorCode.safeParse("403").success).toBe(true);
+  expect(XapiV1_0_3.Schemas.ErrorCode.safeParse("404").success).toBe(true);
+  expect(XapiV1_0_3.Schemas.ErrorCode.safeParse("412").success).toBe(true);
+  expect(XapiV1_0_3.Schemas.ErrorCode.safeParse("500").success).toBe(true);
+  expect(XapiV1_0_3.Schemas.ErrorCode.safeParse("999").success).toBe(false);
+});
+
+test("xAPI concurrency schema validates ETags and conditional headers", () => {
+  expect(
+    XapiV1_0_3.Schemas.Concurrency.safeParse({
+      etag: '"abc123"',
+    }).success,
+  ).toBe(true);
+
+  expect(
+    XapiV1_0_3.Schemas.Concurrency.safeParse({
+      ifMatch: '"abc123"',
+    }).success,
+  ).toBe(true);
+
+  expect(
+    XapiV1_0_3.Schemas.Concurrency.safeParse({
+      ifNoneMatch: '"abc123"',
+    }).success,
+  ).toBe(true);
+
+  expect(XapiV1_0_3.Schemas.Concurrency.safeParse({}).success).toBe(true);
+});
+
+test("xAPI multipart attachment part schema validates attachment data structure", () => {
+  expect(
+    XapiV1_0_3.Schemas.MultipartAttachmentPart.safeParse({
+      headers: {
+        "Content-Type": "image/png",
+        "Content-Transfer-Encoding": "binary",
+        "X-Experience-API-Hash": attachmentSha2,
+      },
+      body: new Uint8Array([0x89, 0x50, 0x4e, 0x47]),
+    }).success,
+  ).toBe(true);
+
+  expect(
+    XapiV1_0_3.Schemas.MultipartAttachmentPart.safeParse({
+      headers: {
+        "Content-Type": "image/png",
+        "Content-Transfer-Encoding": "base64",
+        "X-Experience-API-Hash": attachmentSha2,
+      },
+      body: "iVBORw0KGgoAAAANSUhEUgAAAAUA",
+    }).success,
+  ).toBe(false);
+});
+
+test("xAPI multipart request schema validates statement with attachments", () => {
+  expect(
+    XapiV1_0_3.Schemas.MultipartRequest.safeParse({
+      contentType: "multipart/mixed",
+      parts: [
+        {
+          contentType: "application/json",
+          body: validStatement,
+        },
+        [
+          {
+            headers: {
+              "Content-Type": "image/png",
+              "Content-Transfer-Encoding": "binary",
+              "X-Experience-API-Hash": attachmentSha2,
+            },
+            body: new Uint8Array([0x89, 0x50, 0x4e, 0x47]),
+          },
+        ],
+      ],
+    }).success,
+  ).toBe(true);
+});
+
+test("xAPI resource schema models LRS endpoint definitions", () => {
+  expect(
+    XapiV1_0_3.Schemas.Resource.safeParse({
+      name: "Statements",
+      description: "Store and retrieve xAPI statements",
+      methods: ["GET", "POST", "PUT"],
+    }).success,
+  ).toBe(true);
+
+  expect(
+    XapiV1_0_3.Schemas.Resource.safeParse({
+      name: "Statements",
+      description: "Store and retrieve xAPI statements",
+      methods: [],
+    }).success,
+  ).toBe(false);
+});
+
+test("xAPI request and response headers are properly enumerated", () => {
+  expect(XapiV1_0_3.Schemas.RequestHeader.safeParse("Authorization").success).toBe(true);
+  expect(XapiV1_0_3.Schemas.RequestHeader.safeParse("If-Match").success).toBe(true);
+  expect(XapiV1_0_3.Schemas.RequestHeader.safeParse("X-Experience-API-Hash").success).toBe(true);
+  expect(XapiV1_0_3.Schemas.RequestHeader.safeParse("X-Experience-API-Version").success).toBe(true);
+  expect(XapiV1_0_3.Schemas.RequestHeader.safeParse("Custom-Header").success).toBe(false);
+
+  expect(XapiV1_0_3.Schemas.ResponseHeader.safeParse("ETag").success).toBe(true);
+  expect(XapiV1_0_3.Schemas.ResponseHeader.safeParse("X-Experience-API-Consistent-Through").success).toBe(true);
+  expect(XapiV1_0_3.Schemas.ResponseHeader.safeParse("Authorization").success).toBe(false);
+});

package/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "types": ["bun"]
+  },
+  "include": ["src", "test"]
+}

package/vc-data-model-v2_0-zod-templates.md

@@ -0,0 +1,43 @@
+# Verifiable Credentials Data Model 2.0 -> Zod template notes
+
+## Published specification
+
+- W3C Recommendation: `https://www.w3.org/TR/vc-data-model-2.0/`
+
+This note accompanies `packages/contracts/src/vc-data-model/v2_0/`.
+
+---
+
+## 1. Scope choice
+
+VC Data Model 2.0 does not ship as a single 1EdTech-style JSON schema bundle that maps one-to-one to this repository's versioned schema-port workflow.
+
+To integrate it cleanly for Open Badges 3.0 and CLR 2.0, this package implements the shared VC and credential primitives used by both standards:
+
+- `VerifiableCredentialSchema`
+- `VerifiablePresentationSchema`
+- `CredentialSubjectSchema`
+- `CredentialSchemaSchema`
+- `CredentialStatusSchema`
+- `RefreshServiceSchema`
+- `TermsOfUseSchema`
+- `ProofSchema`
+- `EvidenceSchema`
+- `HolderSchema`
+
+Grouped as `VcDataModel20DerivedZodTemplates`.
+
+---
+
+## 2. Relationship to Open Badges and CLR
+
+This VC Data Model surface is intentionally shared infrastructure. Open Badges 3.0 and CLR 2.0 version bundles compose on top of it, with each standard adding its own context/type constraints and domain objects.
+
+This avoids duplicated logic and keeps cross-standard behavior aligned.
+
+---
+
+## 3. Public surface and naming
+
+- package-root namespace: `VcDataModelV2_0`
+- package subpath: `@conform-ed/contracts/vc-data-model/v2_0`

package/xapi-zod-templates.md

@@ -0,0 +1,95 @@
+# xAPI Zod templates
+
+## Scope
+
+This bundle covers:
+
+- xAPI 1.0.3 statement/data models
+- IEEE xAPI 2.0 statement/data models
+- Statement result containers and Person objects
+- LRS document resources (State, AgentProfile, ActivityProfile)
+- Statement, Agents, and Activities resource query shapes
+- Document id list responses for State/Profile resources
+- LRS resource and endpoint schemas
+- HTTP transport and concurrency control (ETags, conditional requests)
+- Multipart attachment transmission with binary hashing
+- Error handling and HTTP status codes
+- About/version metadata
+
+## Source references
+
+These documents were used as normative references while modeling the xAPI payload contracts:
+
+- ADL xAPI 1.0.3 spec documents:
+  - `xAPI-About.md`
+  - `xAPI-Data.md`
+  - `xAPI-Communication.md` (including LRS and statement submission guidance)
+- IEEE xAPI 2.0 base-standard documents:
+  - `9274.1.1 xAPI Base Standard Front Matter.md`
+  - `9274.1.1 xAPI Base Standard Overview.md`
+  - `9274.1.1 xAPI Base Standard for Content.md`
+  - `9274.1.1 xAPI Base Standard for LRSs.md`
+
+## Entry points
+
+- `@conform-ed/contracts/xapi`
+- `@conform-ed/contracts/xapi/v1_0_3`
+- `@conform-ed/contracts/xapi/v2_0`
+
+## Schemas
+
+### Core Data Models
+
+- `Agent` / `Group` — Actor types with inverse-functional identifier validation
+- `Person` — Aggregated Agents Resource response with array-valued identifiers
+- `Verb` — Action vocabulary with display language support
+- `Activity` — Learning object with optional activity definition
+- `Result` — Statement outcome with score, success, completion, and duration
+- `Context` — Contextual information including registration, language, and activities
+- `ContextAgent` / `ContextGroup` (IEEE 2.0) — Statement-scoped contextual agents/groups with optional `relevantTypes`
+- `Attachment` — Binary attachment metadata with SHA2 hashing
+- `Statement` — Complete xAPI statement combining actor, verb, object, result, and context
+- `StatementResult` — `/statements` query response envelope containing `statements` plus optional `more`
+
+### LRS Document Resources
+
+- `StatementsQuery` — `/statements` query parameters (statement ids, agent/activity filters, date windows, format, attachments)
+- `AgentsResourceQuery` — `/agents` request payload/query wrapper for a target Agent
+- `ActivitiesResourceQuery` — `/activities` request payload/query wrapper for a target Activity id
+- `StateDocumentQuery` — Request parameters for state document access (activityId, agent, stateId, registration)
+- `StateDocumentListingQuery` — Request parameters for listing state ids, including optional `since`
+- `AgentProfileDocumentQuery` — Request parameters for agent profile access
+- `AgentProfileDocumentListingQuery` — Request parameters for listing agent profile ids
+- `ActivityProfileDocumentQuery` — Request parameters for activity profile access
+- `ActivityProfileDocumentListingQuery` — Request parameters for listing activity profile ids
+- `XapiDocument` — Response envelope for document retrieval (contentType, body, etag, lastModified)
+- `XapiDocumentIdList` — Top-level JSON array response for State/Profile id listings
+
+### Transport and Concurrency
+
+- `HttpMethod` — Enumeration of LRS HTTP methods (GET, HEAD, PUT, POST, DELETE)
+- `RequestHeader` — HTTP request headers supported by xAPI (Authorization, If-Match, etc.)
+- `ResponseHeader` — HTTP response headers (ETag, X-Experience-API-Version, etc.)
+- `Concurrency` — Concurrency control with ETag and conditional request headers (If-Match, If-None-Match)
+- `ErrorCode` — Standard HTTP error codes returned by LRS (400, 401, 403, 404, 409, 411, 412, 413, 500, 501)
+- `ErrorResponse` — Error payload with code, message, and optional details
+
+### Multipart Attachments
+
+- `MultipartAttachmentPart` — Binary attachment data with required Content-Type, Content-Transfer-Encoding (binary), and X-Experience-API-Hash headers
+- `MultipartRequest` — Full multipart/mixed request envelope with JSON statement(s) followed by binary attachment parts
+
+### Service Metadata
+
+- `AboutResource` — LRS about/version endpoint response listing supported xAPI versions
+- `Resource` — Endpoint definition with name, description, and supported HTTP methods
+
+## Notes
+
+- Structured statement objects and all domain types are strict (`strictObject()`), catching misspelled or extra properties.
+- Document bodies are intentionally permissive (`z.unknown()`) because xAPI allows arbitrary document content types.
+- Agent and Group schemas enforce at-least-one-identifier validation via `.refine()`, matching the spec intent that agents must be identifiable.
+- Person objects are modeled separately from Agents because the `/agents` resource returns array-valued identifier fields rather than single IFIs.
+- Concurrency control and multipart transmission are modeled as separate concerns for flexibility in HTTP client implementations.
+- Version 2.0 reuses the 1.0.3 model where structurally equivalent, but overrides Context/Statement-family schemas to add IEEE `contextAgent`, `contextGroup`, and `relevantTypes`.
+- Strict error codes (400, 401, 403, 404, 409, 411, 412, 413, 500, 501) align with xAPI specification guidance for LRS error responses.