@conform-ed/contracts 0.0.3

package/cc-v1_4-zod-templates.md

@@ -0,0 +1,247 @@
+# Common Cartridge 1.4 candidate-final XSD bundle → Zod template notes
+
+## Published specification
+
+- Public implementation guide consulted for this port: `https://www.imsglobal.org/spec/cc/v1p4/impl/`
+- Likely published-final landing page: `https://www.imsglobal.org/spec/cc/v1p4`
+
+This note accompanies the split source under `packages/contracts/src/common-cartridge/v1_4/`.
+
+The Common Cartridge 1.4 candidate-final bundle is materially broader than the existing 1.3 bundle: it includes multiple manifest profiles, additional shared resource schemas, imported LTI support schemas, extension schemas, and VDEX support files. This document records the choices made to keep the 1.4 port close to the existing `v1_3` style while still matching the shape of the real source set.
+
+---
+
+## 1. What was analyzed
+
+The templates are based on the local source bundle under `tmp/cc/v1_4/`:
+
+- `core/`
+- `thin/`
+- `k12/`
+- `shared/`
+- `extension/`
+- `vdex/`
+
+Representative entry-point XSDs:
+
+- `core/ccv1p4_imscp_v1p2_v1p0.xsd`
+- `thin/ccv1p4_imscp_v1p2_v1p0.xsd`
+- `k12/ccv1p4_imscp_v1p2_v1p0.xsd`
+- `k12/ccv1p4_imscp_v1p2_v1p0.xsd.thin`
+- `shared/ccv1p4_imslticc_v1p4.xsd`
+- `extension/cc_extresource_assignmentv1p0_v1p0.xsd`
+- `extension/ims_openvideov1p0_v1p0.xsd`
+- `vdex/imsvdex_v1p0.xsd`
+
+The candidate final implementation guide at `https://www.imsglobal.org/spec/cc/v1p4/impl` was also consulted to confirm the intended profile split and the relationship between the standard, Thin CC, and K-12 variants.
+
+---
+
+## 2. The main structural decision: mirror the source bundle layout
+
+### Problem
+
+Common Cartridge 1.3 fit comfortably in one flat implementation directory because the source bundle itself was flat. Common Cartridge 1.4 does not:
+
+- `core`, `thin`, and `k12` reuse several of the same filenames
+- the K-12 directory contains both a standard manifest XSD and a separate `.xsd.thin` variant
+- the shared/extension/vdex areas introduce several new families that are not just minor renames of 1.3 files
+
+Flattening all of that into a single directory would require invented file renames for source collisions.
+
+### Decision
+
+The port mirrors the source bundle under `src/common-cartridge/v1_4/`:
+
+- `core/`
+- `thin/`
+- `k12/`
+- `shared/`
+- `extension/`
+- `vdex/`
+
+Shared helper modules remain at the version root:
+
+- `shared.ts`
+- `lom-internal.ts`
+- `index.ts`
+
+### Rationale
+
+This preserves the strongest existing convention — one TypeScript module per source XSD — while making the 1.4 profile split obvious instead of hiding it behind ad hoc file renames.
+
+---
+
+## 3. The package-surface decision: versioned namespaces at the root
+
+### Problem
+
+Once a second Common Cartridge version is exported from the package root, flat re-exports collide immediately:
+
+- `CommonCartridgeManifestProfileDocumentSchema`
+- `LomManifestDocumentSchema`
+- `CurriculumStandardsMetadataSetSchema`
+- and many more
+
+### Decision
+
+The package root now exports versioned namespaces for Common Cartridge:
+
+- `CommonCartridgeV1_3`
+- `CommonCartridgeV1_4`
+
+The version barrel at `src/common-cartridge/v1_4/index.ts` still exports a flat surface **within the version**, because that remains convenient and collision-free inside a versioned namespace.
+
+### Rationale
+
+This is the least disruptive way to support side-by-side versions without renaming every existing schema export in `v1_3`.
+
+---
+
+## 4. Profile handling decisions
+
+## 4.1 Core manifest profile
+
+The core manifest module stays very close to the 1.3 implementation:
+
+- updated resource type enumeration for 1.4
+- updated manifest schema labels and `schemaversion`
+- updated QTI resource type strings from `imscc_xmlv1p3` to `imscc_xmlv1p4`
+- existing Schematron-derived duplicate/dependency/item checks carried forward
+
+The main 1.4 additions in the resource type vocabulary are:
+
+- `imsov_xmlv1p0`
+- `imsov_zipv1p0`
+- `imsqti_zipv3p0`
+
+## 4.2 Thin manifest profile
+
+The Thin CC manifest genuinely differs structurally, so it has its own dedicated module rather than just a renamed alias:
+
+- only `imsbasiclti_xmlv1p4` and `imswl_xmlv1p4` resource types are allowed
+- dependency support is removed
+- manifest-level authorizations are removed
+- the resource body can carry embedded `cartridge_basiclti_link` or `webLink` XML
+
+The Zod model therefore makes those embedded resource payloads explicit and validates that the inline XML matches the declared resource `type`.
+
+## 4.3 K-12 manifest profiles
+
+The provided K-12 packaging XSDs are the tricky part.
+
+The local `k12/ccv1p4_imscp_v1p2_v1p0.xsd` is effectively the same packaging grammar as the core manifest, and `k12/ccv1p4_imscp_v1p2_v1p0.xsd.thin` is effectively the Thin CC grammar. The stricter K-12 rules in the local bundle live primarily in the standalone K-12 LOM profile XSDs, not in a materially different manifest grammar.
+
+### Decision
+
+The port treats the K-12 manifest modules as profile-specific aliases of the core and thin manifest schemas:
+
+- `K12CommonCartridge...` aliases the core manifest surface
+- `K12ThinCommonCartridge...` aliases the thin manifest surface
+
+The standalone K-12 LOM schemas carry the extra K-12 metadata requirements.
+
+### Rationale
+
+This follows the actual local source set instead of inventing packaging constraints that are not expressed in the shipped `imscp` XSDs.
+
+This is one of the places where a different choice would have been possible: we could have added extra K-12 manifest-level refinements based on prose expectations alone. The implementation deliberately did **not** do that because the local packaging XSDs do not wire those stricter LOM profiles into the manifest imports.
+
+---
+
+## 5. LOM profile decisions
+
+The shared `lom-internal.ts` still generates normalized LOM object schemas, but 1.4 adds more than one practical LOM profile:
+
+- core manifest/resource
+- Thin CC manifest/resource
+- K-12 manifest/resource
+- CC LTI link metadata
+
+### Decision
+
+- core and thin manifest/resource LOM profiles remain loose-value profiles
+- K-12 manifest LOM adds required `general.keyword`
+- K-12 resource LOM adds required:
+  - `general`
+  - `general.title`
+  - `general.keyword`
+  - at least one `educational`
+  - `educational.intendedEndUserRole`
+  - `educational.typicalAgeRange`
+- LTI link metadata keeps the tighter vocabulary-checked profile carried forward from 1.3
+
+### Rationale
+
+This keeps the general LOM modeling approach unchanged while giving the K-12 standalone metadata documents the stricter rules that actually differ in the 1.4 bundle.
+
+---
+
+## 6. Shared/additional schema decisions
+
+## 6.1 `ccv1p4_imscsmd_v1p1.xsd`
+
+This is the 1.3 curriculum-standards model with one meaningful additive change:
+
+- `LabelledGUID.Type` adds optional `caseItemURI`
+
+That was modeled directly.
+
+## 6.2 LTI support schemas
+
+Common Cartridge 1.4 bundles more of the LTI support stack locally:
+
+- `imslticm_v1p0`
+- `imslticp_v1p0`
+- `imsbasiclti_v1p0p1`
+- `ccv1p4_imslticc_v1p4`
+
+These are modeled as normalized nested objects rather than generic XML trees so that Thin CC embedded resources and standalone LTI descriptors are usable directly.
+
+## 6.3 Assignment, line item, and accessibility metadata
+
+These three families map cleanly to plain objects:
+
+- assignment extension
+- AGS line item
+- accessibility metadata
+
+They are represented directly with only the obvious scalar/enum normalization.
+
+## 6.4 VDEX support files
+
+The 1.4 bundle includes:
+
+- `imsmd_loose_v1p3p2.xsd`
+- `imsvdex_v1p0.xsd`
+
+`imsmd_loose` is modeled as a standalone loose LOM document. `imsvdex` is modeled as a normalized vocabulary tree with recursive `term` nodes and a small refinement to detect duplicate `termIdentifier` values.
+
+## 6.5 Open Video
+
+Open Video is the largest new schema family in the bundle.
+
+### Decision
+
+It is modeled as an explicit normalized object graph rather than collapsed to generic XML, but the semantic refinements stay intentionally focused:
+
+- duplicate contributor IDs
+- duplicate recorder IDs
+- `stream.recorderID` must reference an existing recorder
+
+### Rationale
+
+This keeps the schema useful while avoiding a large amount of fragile hand-coded prose validation that would go beyond the level of rigor used elsewhere in the package.
+
+---
+
+## 7. Remaining approximations
+
+The 1.4 port still makes a few deliberate approximations:
+
+1. K-12 manifest modules alias the core/thin packaging grammars instead of inventing additional manifest-level metadata rules.
+2. Open Video does not attempt to encode every prose-level invariant from the candidate final text.
+3. Thin/resource embedded XML is normalized to explicit `cartridge_basiclti_link` / `webLink` object slots instead of preserving heterogeneous XML child order.
+4. Remote include files such as the shared extension helper XSDs are still represented through the existing `XmlExtensionNode` / foreign-attribute pattern rather than being ported as literal helper ASTs.
+
+These are intentional consistency choices, not omissions.

package/clr-v2_0-zod-templates.md

@@ -0,0 +1,117 @@
+# Comprehensive Learner Record 2.0 JSON schema bundle -> Zod template notes
+
+## Published specification
+
+- Main specification: `https://www.imsglobal.org/spec/clr/v2p0/`
+- Main spec document: `https://www.imsglobal.org/spec/clr/v2p0/main/`
+- JSON-LD context: `https://purl.imsglobal.org/spec/clr/v2p0/context-2.0.1.json`
+- Published JSON schemas used for this port:
+  - `https://purl.imsglobal.org/spec/clr/v2p0/schema/json/clr_v2p0_clrcredential_schema.json`
+  - `https://purl.imsglobal.org/spec/clr/v2p0/schema/json/clr_v2p0_achievementcredential_schema.json`
+  - `https://purl.imsglobal.org/spec/clr/v2p0/schema/json/clr_v2p0_endorsementcredential_schema.json`
+  - `https://purl.imsglobal.org/spec/clr/v2p0/schema/json/clr_v2p0_getclrcredentialsresponse_schema.json`
+  - `https://purl.imsglobal.org/spec/clr/v2p0/schema/json/clr_v2p0_profile_schema.json`
+  - `https://purl.imsglobal.org/spec/clr/v2p0/schema/json/clr_v2p0_imsx_statusinfo_schema.json`
+
+This note accompanies the versioned source under `packages/contracts/src/clr/v2_0/`.
+
+---
+
+## 1. What was implemented
+
+CLR 2.0 is not an XSD family like the QTI and Common Cartridge ports. The published source of truth here is the JSON Schema and JSON-LD credential model bundle.
+
+The port therefore models the published JSON-schema entry points rather than inventing XML-style document wrappers:
+
+- `ClrCredentialSchema`
+- `AchievementCredentialSchema`
+- `EndorsementCredentialSchema`
+- `GetClrCredentialsResponseSchema`
+- `ProfileSchema`
+- `ImsxStatusInfoSchema`
+
+The version barrel exports these as `ClrV2_0`, and `Clr20DerivedZodTemplates` collects the published entry points in one place.
+
+---
+
+## 2. Main structural choice: extract shared VC/credential primitives
+
+CLR 2.0 clearly overlaps with the same broader digital-credential model family used by Open Badges 3.0:
+
+- `AchievementCredential`
+- `EndorsementCredential`
+- `Profile`
+- `Achievement`
+- `Result`
+- `Proof`
+- and the surrounding verifiable-credential primitives
+
+The implementation now uses a shared versioned layer for common primitives:
+
+- `src/vc-data-model/v2_0/` for VC-level/shared primitives
+- `src/open-badges/v3_0/shared.ts` for the shared OB/CLR credential model graph
+
+CLR composes from that shared model and keeps only CLR-specific wrappers in `src/clr/v2_0/`.
+
+### Rationale
+
+- it removes duplicated credential-model logic between CLR and Open Badges
+- it keeps VC/credential semantics aligned across both standards
+- it still preserves versioned, explicit standard surfaces at the package boundary
+
+---
+
+## 3. Main validation choice: prefer normative credential arrays over the JSON-LD compaction fallback
+
+The published JSON Schema files are adapted for JSON-LD compaction, so several properties are more permissive than the underlying normative intent:
+
+- credential `@context`
+- credential `type`
+- several single-or-array properties
+
+For the Zod port, the repeated-value properties still accept either a single value or an array where that is useful for real payloads, but the key credential identity fields are intentionally made more semantic:
+
+- `ClrCredential` requires a credential `type` array containing `VerifiableCredential` and `ClrCredential`
+- `AchievementCredential` requires `VerifiableCredential` and one of `AchievementCredential` / `OpenBadgeCredential`
+- `EndorsementCredential` requires `VerifiableCredential` and `EndorsementCredential`
+- credential `@context` arrays are validated against the expected CLR / OB / VC ordering rather than accepting any arbitrary single context value
+
+### Rationale
+
+The published JSON Schema bundle under-enforces some of those rules in order to support JSON-LD compaction patterns. For this repo, the more useful default is to validate the portable, explicit credential shapes that implementers are most likely to exchange.
+
+---
+
+## 4. Extensibility choice: preserve open object surfaces where the spec does
+
+Most CLR credential-model objects are extensible in the published JSON Schema bundle.
+
+The Zod port mirrors that with passthrough object schemas for the credential-model objects, while the stricter API-envelope schemas remain strict:
+
+- passthrough for credential/profile/achievement-style objects
+- strict for `GetClrCredentialsResponse`
+- strict for `ImsxStatusInfo`
+
+### Rationale
+
+This keeps the CLR credential objects usable for real JSON-LD / extension-heavy payloads without silently tightening the spec into a closed-world model.
+
+---
+
+## 5. Public surface and naming
+
+The contracts package now exposes CLR 2.0 in the same style as the other standards:
+
+- package-root namespace: `ClrV2_0`
+- package subpath: `@conform-ed/contracts/clr/v2_0`
+
+The source modules mirror the published schema artifact names where that remains useful:
+
+- `clr_v2p0_clrcredential_schema.ts`
+- `clr_v2p0_achievementcredential_schema.ts`
+- `clr_v2p0_endorsementcredential_schema.ts`
+- `clr_v2p0_profile_schema.ts`
+- `clr_v2p0_getclrcredentialsresponse_schema.ts`
+- `clr_v2p0_imsx_statusinfo_schema.ts`
+
+with `shared.ts` holding the common credential-model pieces used across those entry points.

package/cmi5-v1_0-zod-templates.md

@@ -0,0 +1,9 @@
+# cmi5 schema notes
+
+The cmi5 contract bundle models the Quartz course-structure XML surface:
+
+- `Cmi5V1_0.CourseStructureDocument` — combined courseStructure document and keyword extension
+- `Cmi5V1_0.CourseStructure` — course, objectives, and recursive AU/block tree
+- `Cmi5V1_0.KeywordExtension` — keyword dictionary used by the extension examples
+
+This bundle intentionally covers the XML data model from the spec artifacts; runtime xAPI launch/state/statement behavior stays in the cmi5 apps.

package/lti-zod-templates.md

@@ -0,0 +1,11 @@
+# LTI schema notes
+
+The LTI contract bundle is split by spec family:
+
+- `LtiV1_3` — normalized LTI 1.3 core launch claims
+- `LtiDeepLinkingV2_0` — deep linking request settings and response content items
+- `LtiAgsV2_0` — assignment and grade services endpoint, line item, score, and result payloads
+- `LtiNrpsV2_0` — names and roles service claim plus membership container
+- `LtiProctoringV1_0` — proctoring launch messages and assessment-control payloads
+
+The schemas use normalized camelCase field names so they are easy to use from the adapter reference app and runner fixtures.

package/oneroster-v1_2-zod-templates.md

@@ -0,0 +1,76 @@
+# OneRoster 1.2 JSON schema/OpenAPI bundle -> Zod template notes
+
+## Published specification
+
+- Main specification: `https://www.imsglobal.org/spec/oneroster/v1p2/`
+- Rostering service information model: `https://www.imsglobal.org/spec/oneroster/v1p2/rostering/info`
+- Rostering service REST binding: `https://www.imsglobal.org/spec/oneroster/v1p2/rostering/bind/rest`
+- Rostering REST binding permalink: `https://www.imsglobal.org/spec/oneroster/v1p2/rostering-restbinding/`
+- Gradebook service information model: `https://www.imsglobal.org/spec/oneroster/v1p2/gradebook/info`
+- Gradebook service REST binding: `https://www.imsglobal.org/spec/oneroster/v1p2/gradebook/bind/rest`
+- Gradebook REST binding permalink: `https://www.imsglobal.org/spec/oneroster/v1p2/gradebook-restbinding/`
+- Resource service information model: `https://www.imsglobal.org/spec/oneroster/v1p2/resource/info`
+- Resource service REST binding: `https://www.imsglobal.org/spec/oneroster/v1p2/resource/bind/rest`
+- Resource REST binding permalink: `https://www.imsglobal.org/spec/oneroster/v1p2/resources-restbinding/`
+- CSV binding: `https://www.imsglobal.org/spec/oneroster/v1p2/bind/csv/`
+- OpenAPI 3 JSON sources used directly:
+  - `https://purl.imsglobal.org/spec/or/v1p2/schema/openapi/onerosterv1p2rostersservice_openapi3_v1p0.json`
+  - `https://purl.imsglobal.org/spec/or/v1p2/schema/openapi/onerosterv1p2gradebookservice_openapi3_v1p0.json`
+  - `https://purl.imsglobal.org/spec/or/v1p2/schema/openapi/onerosterv1p2resourcesservice_openapi3_v1p0.json`
+
+This note accompanies `packages/contracts/src/oneroster/v1_2/`.
+
+---
+
+## 1. What was implemented
+
+This port models:
+
+- rostering
+- gradebook
+- resource
+- endpoint-specific REST binding operation payload contracts for all published operations
+- CSV binding row/document/package contracts for the published CSV files
+
+The public package surface is:
+
+- root namespace: `OneRosterV1_2`
+- subpath export: `@conform-ed/contracts/oneroster/v1_2`
+
+The version barrel publishes the service schemas and `OneRoster12DerivedZodTemplates`.
+
+---
+
+## 2. Structural choices
+
+The implementation is split into:
+
+- `shared.ts` for common primitives (`metadata`, status vocabularies, GUID refs, IMSX status envelope)
+- `or_v1p2_rostering_service_schema.ts`
+- `or_v1p2_gradebook_service_schema.ts`
+- `or_v1p2_resource_service_schema.ts`
+- `or_v1p2_rostering_restbinding_schema.ts`
+- `or_v1p2_gradebook_restbinding_schema.ts`
+- `or_v1p2_resource_restbinding_schema.ts`
+- `or_v1p2_csv_binding_schema.ts`
+
+This mirrors the OneRoster 1.2 service split and avoids duplicating shared shapes across services.
+
+---
+
+## 3. Validation choices
+
+- objects marked `additionalProperties: false` in the published OpenAPI schemas are modeled as strict Zod objects
+- `MetadataDType` and `CredentialDType` stay open where the source model is open
+- extensible vocabularies are modeled as:
+  - defined enum values
+  - plus `ext:*` custom values where the specification allows extension tokens
+- date/date-time and URI fields use explicit ISO/URL validators
+
+---
+
+## 4. CSV binding modeling choice
+
+The CSV layer is modeled as raw row/document schemas (string cell values) keyed by published column headers, plus a package-level aggregate schema.
+
+For manifest keys that appear in the spec with trailing `*` markers, the schema accepts both starred and unstarred variants and requires at least one to be present.

package/open-badges-v3_0-zod-templates.md

@@ -0,0 +1,66 @@
+# Open Badges 3.0 JSON schema bundle -> Zod template notes
+
+## Published specification
+
+- Main specification: `https://www.imsglobal.org/spec/ob/v3p0/`
+- Main spec document: `https://www.imsglobal.org/spec/ob/v3p0/main/`
+- Implementation guide: `https://www.imsglobal.org/spec/ob/v3p0/impl/`
+- JSON-LD context: `https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.3.json`
+- Published JSON schemas used for this port:
+  - `https://purl.imsglobal.org/spec/ob/v3p0/schema/json/ob_v3p0_achievementcredential_schema.json`
+  - `https://purl.imsglobal.org/spec/ob/v3p0/schema/json/ob_v3p0_endorsementcredential_schema.json`
+  - `https://purl.imsglobal.org/spec/ob/v3p0/schema/json/ob_v3p0_getopenbadgecredentialsresponse_schema.json`
+  - `https://purl.imsglobal.org/spec/ob/v3p0/schema/json/ob_v3p0_profile_schema.json`
+  - `https://purl.imsglobal.org/spec/ob/v3p0/schema/json/ob_v3p0_imsx_statusinfo_schema.json`
+
+This note accompanies `packages/contracts/src/open-badges/v3_0/`.
+
+---
+
+## 1. What was implemented
+
+The Open Badges 3.0 port models the published JSON-schema entry points directly:
+
+- `AchievementCredentialSchema` (`OpenBadgeCredentialSchema` alias)
+- `EndorsementCredentialSchema`
+- `GetOpenBadgeCredentialsResponseSchema`
+- `ProfileSchema`
+- `ImsxStatusInfoSchema`
+
+The version barrel exports these as `OpenBadgesV3_0`, and `OpenBadges30DerivedZodTemplates` groups the top-level published entries.
+
+---
+
+## 2. Shared-model choice
+
+Open Badges 3.0 and CLR 2.0 reuse almost the same credential model graph (Achievement, Profile, EndorsementCredential, Result, Proof, and related primitives). Rather than duplicating those pieces again, this port centralizes the cross-standard primitives in:
+
+- `src/vc-data-model/v2_0/` for VC-level/shared credential primitives
+- `src/open-badges/v3_0/shared.ts` for OB-specific profile/achievement structures
+
+CLR now composes from this same OB/VC model layer.
+
+---
+
+## 3. Validation strictness choice
+
+Like CLR, the OB 3.0 schemas are JSON-LD-compaction-friendly and permissive in places. The Zod port keeps extension-friendly object surfaces, but tightens core credential identity semantics:
+
+- `AchievementCredential` requires `VerifiableCredential` plus one of `AchievementCredential` / `OpenBadgeCredential`
+- `EndorsementCredential` requires `VerifiableCredential` plus `EndorsementCredential`
+- `@context` ordering enforces expected OB 3.0 context prefixes while still allowing additional context entries
+
+---
+
+## 4. Public surface and naming
+
+- package-root namespace: `OpenBadgesV3_0`
+- package subpath: `@conform-ed/contracts/open-badges/v3_0`
+
+Source modules mirror the published artifact names:
+
+- `ob_v3p0_achievementcredential_schema.ts`
+- `ob_v3p0_endorsementcredential_schema.ts`
+- `ob_v3p0_getopenbadgecredentialsresponse_schema.ts`
+- `ob_v3p0_profile_schema.ts`
+- `ob_v3p0_imsx_statusinfo_schema.ts`

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@conform-ed/contracts",
+  "version": "0.0.3",
+  "type": "module",
+  "module": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./caliper/v1_2": "./src/caliper/v1_2/index.ts",
+    "./case/v1_1": "./src/case/v1_1/index.ts",
+    "./cat/v1_0": "./src/cat/v1_0/index.ts",
+    "./clr/v2_0": "./src/clr/v2_0/index.ts",
+    "./common-cartridge/v1_3": "./src/common-cartridge/v1_3/index.ts",
+    "./common-cartridge/v1_4": "./src/common-cartridge/v1_4/index.ts",
+    "./cmi5": "./src/cmi5/index.ts",
+    "./cmi5/v1_0": "./src/cmi5/v1_0/index.ts",
+    "./xapi": "./src/xapi/index.ts",
+    "./xapi/v1_0_3": "./src/xapi/v1_0_3/index.ts",
+    "./xapi/v2_0": "./src/xapi/v2_0/index.ts",
+    "./lti": "./src/lti/index.ts",
+    "./lti/ags/v2_0": "./src/lti/ags/v2_0/index.ts",
+    "./lti/deep-linking/v2_0": "./src/lti/deep-linking/v2_0/index.ts",
+    "./lti/nrps/v2_0": "./src/lti/nrps/v2_0/index.ts",
+    "./lti/proctoring/v1_0": "./src/lti/proctoring/v1_0/index.ts",
+    "./lti/v1_3": "./src/lti/v1_3/index.ts",
+    "./open-badges/v3_0": "./src/open-badges/v3_0/index.ts",
+    "./oneroster/v1_2": "./src/oneroster/v1_2/index.ts",
+    "./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"
+  },
+  "scripts": {
+    "build": "tsgo --noEmit",
+    "typecheck": "tsgo --noEmit",
+    "lint": "oxlint --config ../../.oxlintrc.jsonc .",
+    "format": "oxfmt --config ../../.oxfmtrc.jsonc --check .",
+    "test": "bun test"
+  },
+  "devDependencies": {
+    "fast-xml-parser": "^5.3.1"
+  }
+}

package/qti-v2_1-zod-templates.md

@@ -0,0 +1,45 @@
+# QTI 2.1 Zod templates
+
+## Published specification
+
+- Overview: `https://www.imsglobal.org/question/qtiv2p1/imsqti_oviewv2p1.html`
+- Assessment/item/test information model: `https://www.imsglobal.org/question/qtiv2p1/imsqti_infov2p1.html`
+- Results Reporting v2.1: `https://www.imsglobal.org/question/qtiv2p1/imsqti_resultv2p1.html`
+
+`tmp/qti/2.1/` ships a small bundle of entry-point XSDs plus imported helper trees (`metadata/`, `other/`). The implementation lives in `packages/contracts/src/qti/v2_1/` and follows the same normalized parsed-XML style as the existing QTI 3.0.1 port: arrays are pluralized, embedded XML extension points are normalized into explicit `extensions` / `foreignAttributes`, and public entry points are exposed as document schemas plus a version registry.
+
+## Implementation shape
+
+- `imsqti_v2p1p2.ts` covers the main assessment object family:
+  - `assessmentItem`
+  - `assessmentSection`
+  - `assessmentTest`
+  - declarations
+  - processing fragments
+  - item body / feedback / interaction nodes
+- `imsqti_metadata_v2p1.ts` covers `qtiMetadata`
+- `imsqti_result_v2p1.ts` covers `assessmentResult`
+- `imsqti_usagedata_v2p1.ts` covers `usageData`
+- `qtiv2p1_imscpv1p2_v1p0.ts` covers the QTI 2.1 content-package profile
+- `apipv1p0_qtiextv2p1_v1p0.ts` covers the APIP accessibility extension surface used from items/feedback
+
+## Key choices
+
+1. QTI 2.1 and QTI 2.2 share one internal 2.x implementation core because the source domain model is structurally the same; the version directories only specialize the places where the bundles materially differ.
+2. HTML / XHTML / MathML body content is normalized as generic recursive content nodes instead of one exported Zod schema per markup tag. The domain objects still stay explicit, but the huge markup vocabulary remains tractable.
+3. APIP is modeled as a focused normalized accessibility surface rather than a full schema-for-schema transcription of every auxiliary APIP type. The item-facing accessibility structures are explicit; deeper companion-material payload details stay permissive.
+4. The bundled MathML helper tree is incomplete locally. That does not block the port because those imported vocabularies are treated as generic normalized content subtrees rather than locally-resolved schema dependencies.
+
+## QTI Results Reporting assessment (v2.1)
+
+QTI Results Reporting is published as a distinct document set within the QTI family, but for implementation purposes in this repo it is already covered in the versioned QTI contract surface:
+
+- `imsqti_result_v2p1.ts` exposes `QtiAssessmentResultDocumentSchema`
+- `imsqti_usagedata_v2p1.ts` exposes `QtiUsageDataDocumentSchema`
+- `src/qti/v2_1/index.ts` includes both under `Qti21DerivedZodTemplates`
+
+Assessment outcome for v2.1:
+
+1. It is a separate spec document family, but not a separate package requirement in this repo.
+2. Current coverage is functionally in place for results (`assessmentResult`) and usage (`usageData`) document entry points.
+3. No additional standalone `qti-results-reporting` package is required unless we later want a cross-version aggregate facade.

package/qti-v2_2-zod-templates.md

@@ -0,0 +1,32 @@
+# QTI 2.2 Zod templates
+
+## Published specification
+
+- Overview: `https://www.imsglobal.org/question/qtiv2p2/imsqti_v2p2_oview.html`
+
+`tmp/qti/2.2/` extends the 2.1 model with stimulus documents, HTML5 helper XSDs, curriculum standards metadata, richer APIP accessibility, and a larger QTI content-package profile. The implementation lives in `packages/contracts/src/qti/v2_2/` and keeps the same normalized public style as the rest of this package.
+
+## Implementation shape
+
+- `imsqti_v2p2p4.ts` covers the main assessment object family:
+  - `assessmentItem`
+  - `assessmentSection`
+  - `assessmentStimulus`
+  - `assessmentTest`
+  - declarations
+  - processing fragments
+  - item / stimulus body / feedback / interaction nodes
+- `imsqtiv2p2p4_html5_v1p0.ts` exports the normalized HTML5-oriented content helpers used by the main schemas
+- `imsqti_metadata_v2p2.ts` covers `qtiMetadata`
+- `imsqti_result_v2p2.ts` covers `assessmentResult`
+- `imsqti_usagedata_v2p2.ts` covers `usageData`
+- `qtiv2p2_csm_v2p2.ts` covers curriculum standards metadata
+- `qtiv2p2_imscpv1p2_v1p0.ts` covers the QTI 2.2 packaging profile
+- `apipv1p0_qtiextv2p2_v1p0p1.ts` covers the APIP accessibility extension surface
+
+## Key choices
+
+1. QTI 2.2 reuses the shared 2.x internal implementation with version-specific switches for stimulus support, scoring-mode metadata, curriculum standards metadata, APIP supplemental accessibility, and packaging resource types.
+2. The HTML5 XSD is represented by normalized generic content nodes instead of hundreds of exported per-tag schemas. This matches the practical role of those types in the source bundle: markup containers, not core assessment domain objects.
+3. `assessmentStimulus` and `assessmentStimulusRef` are modeled explicitly because they are a real 2.2 domain addition, not merely more markup.
+4. The local bundle is also missing the full imported MathML / SSML support trees. As with 2.1, that is treated as a content-vocabulary concern rather than a blocker for the QTI domain/object schemas.