@conform-ed/contracts 0.0.3

package/src/cat/v1_0/shared.ts

@@ -0,0 +1,345 @@
+import { z } from "zod";
+
+function strictObject<T extends z.ZodRawShape>(shape: T) {
+  return z.object(shape).strict();
+}
+
+function extensibleEnum<Values extends readonly [string, ...string[]]>(values: Values) {
+  return z.union([z.enum(values), ExtensibleVocabularyValueSchema]);
+}
+
+// Shared validators
+export const UuidSchema = z
+  .string()
+  .regex(/^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[8-9a-b][0-9a-f]{3}-[0-9a-f]{12}$/u);
+const UriSchema = z.string().regex(/^[a-zA-Z][a-zA-Z0-9+.-]*:.+$/u);
+export const DateTimeSchema = z.string().datetime({ offset: true });
+
+const ExtensibleVocabularyValueSchema = z.string().regex(/^(ext:)[a-zA-Z0-9.\-_]+$/u);
+
+export const ExtensionEnumSchema = extensibleEnum;
+
+// Assessment Result status values
+const ASSESSMENT_RESULT_TYPES = ["active", "complete", "incomplete", "paused", "terminated", "pending"] as const;
+
+// Outcome variable types in CAT
+const OUTCOME_VARIABLE_TYPES = [
+  "float",
+  "integer",
+  "boolean",
+  "string",
+  "point",
+  "duration",
+  "pair",
+  "directedPair",
+  "ordered",
+  "multiple",
+  "record",
+] as const;
+
+// Cardinality types for outcome variables
+const OUTCOME_CARDINALITY_TYPES = ["single", "multiple", "ordered", "record"] as const;
+
+export const OutcomeVariableTypeSchema = extensibleEnum(OUTCOME_VARIABLE_TYPES);
+export const OutcomeCardinalitySchema = extensibleEnum(OUTCOME_CARDINALITY_TYPES);
+export const AssessmentResultTypeSchema = extensibleEnum(ASSESSMENT_RESULT_TYPES);
+
+// Outcome variable value (can be various types)
+const OutcomeValueSchema = z.union([z.string(), z.number(), z.boolean(), z.null()]);
+
+/**
+ * Outcome variable - represents a QTI outcome variable from assessment results
+ */
+export const OutcomeVariableSchema = strictObject({
+  identifier: z.string(),
+  cardinality: OutcomeCardinalitySchema,
+  baseType: OutcomeVariableTypeSchema,
+  value: z.union([OutcomeValueSchema, z.array(OutcomeValueSchema)]).optional(),
+});
+
+/**
+ * Response variable - represents a candidate response to an item
+ */
+export const ResponseVariableSchema = strictObject({
+  identifier: z.string(),
+  cardinality: OutcomeCardinalitySchema,
+  baseType: z.string(),
+  value: z.union([OutcomeValueSchema, z.array(OutcomeValueSchema)]).optional(),
+});
+
+/**
+ * Item reference in the item pool
+ */
+export const ItemRefSchema = strictObject({
+  identifier: z.string(),
+  href: UriSchema,
+});
+
+/**
+ * CAT constraint - defines rules for item selection
+ */
+export const CatConstraintSchema = strictObject({
+  type: z.string(),
+  parameters: z.record(z.string(), z.unknown()).optional(),
+});
+
+/**
+ * Item pool - references to available items for adaptive selection
+ */
+export const ItemPoolSchema = strictObject({
+  itemRefs: z.array(ItemRefSchema),
+});
+
+/**
+ * Adaptive section configuration - contains all parameters needed by CAT engine
+ */
+export const SectionDataSchema = strictObject({
+  // Unique identifier for the section in the assessment
+  sectionIdentifier: z.string(),
+
+  // Unique identifier for this particular adaptive section instance
+  assessmentSectionId: UuidSchema,
+
+  // URI pointing to the section resource (QTI or content package)
+  sectionHref: UriSchema,
+
+  // Item pool with available items
+  itemPool: ItemPoolSchema,
+
+  // CAT constraints (e.g., maximum items, target ability, etc.)
+  constraints: z.array(CatConstraintSchema).optional(),
+
+  // Optional item metadata (e.g., IRT parameters, CSM mappings)
+  itemMetadata: z.record(z.string(), z.unknown()).optional(),
+
+  // Optional user demographics for personalization
+  demographics: z.record(z.string(), z.unknown()).optional(),
+
+  // Custom CAT engine parameters (engine-specific)
+  customParameters: z.record(z.string(), z.unknown()).optional(),
+
+  // Creation timestamp
+  createdAt: DateTimeSchema,
+});
+
+/**
+ * Item stage - one or more items to present to the candidate
+ */
+export const ItemStageSchema = strictObject({
+  // Unique identifier for this item stage
+  stageId: UuidSchema,
+
+  // The items to present in this stage
+  items: z.array(ItemRefSchema),
+
+  // Whether the candidate must complete all items in this stage before proceeding
+  mustCompleteAll: z.boolean().optional().default(false),
+
+  // Position of this stage in the test sequence
+  stagePosition: z.number().int().positive().optional(),
+
+  // Total number of stages expected (null if unknown)
+  stagesTotal: z.number().int().positive().nullable().optional(),
+
+  // Adaptive section ID this stage belongs to
+  assessmentSectionId: UuidSchema,
+
+  // Custom properties for the CAT engine
+  customProperties: z.record(z.string(), z.unknown()).optional(),
+});
+
+/**
+ * Assessment result from platform - candidate responses to items
+ */
+export const AssessmentResultSchema = strictObject({
+  // Unique identifier for this result
+  resultId: UuidSchema,
+
+  // The assessment section this result is for
+  assessmentSectionId: UuidSchema,
+
+  // The items being responded to
+  itemsAttempted: z.array(
+    strictObject({
+      itemRef: ItemRefSchema,
+      attemptNumber: z.number().int().positive(),
+    }),
+  ),
+
+  // Candidate responses to items
+  responseVariables: z.array(ResponseVariableSchema).optional(),
+
+  // Outcome variables generated by item processing (e.g., item scores)
+  outcomeVariables: z.array(OutcomeVariableSchema).optional(),
+
+  // Whether the candidate is continuing (true) or finishing (false)
+  continuationRequired: z.boolean(),
+
+  // Timestamp of this result submission
+  submittedAt: DateTimeSchema,
+});
+
+/**
+ * Result report from CAT engine - recommendations and scoring
+ */
+export const CatEngineResultReportSchema = strictObject({
+  // Unique identifier for this report
+  reportId: UuidSchema,
+
+  // Assessment section ID
+  assessmentSectionId: UuidSchema,
+
+  // Estimated ability of the candidate (IRT theta estimate)
+  estimatedAbility: z.number().optional(),
+
+  // Standard error of ability estimate
+  abilityStandardError: z.number().optional(),
+
+  // Overall score/outcome for the section
+  sectionScore: z.number().optional(),
+
+  // Outcome variables to be delivered to the platform
+  outcomeVariables: z.array(OutcomeVariableSchema).optional(),
+
+  // Recommendation (e.g., "continue", "finish")
+  recommendation: z.enum(["continue", "finish", "suspend", "abandon"]),
+
+  // Optional next item stage to present
+  nextStage: ItemStageSchema.optional(),
+
+  // Optional diagnostic information
+  diagnosticData: z.record(z.string(), z.unknown()).optional(),
+
+  // Timestamp of report generation
+  generatedAt: DateTimeSchema,
+});
+
+/**
+ * Session information for CAT delivery
+ */
+export const SessionInfoSchema = strictObject({
+  // Unique session identifier
+  sessionId: UuidSchema,
+
+  // Assessment section ID for this session
+  assessmentSectionId: UuidSchema,
+
+  // Candidate/user identifier
+  candidateId: z.string(),
+
+  // Current session status
+  status: AssessmentResultTypeSchema,
+
+  // Number of items completed so far
+  itemsCompleted: z.number().int().nonnegative(),
+
+  // When session started
+  startedAt: DateTimeSchema,
+
+  // When session ended (null if still active)
+  endedAt: DateTimeSchema.nullable().optional(),
+
+  // Custom session data
+  customData: z.record(z.string(), z.unknown()).optional(),
+});
+
+/**
+ * Request payloads for CAT operations
+ */
+
+export const CreateSectionRequestSchema = strictObject({
+  sectionData: SectionDataSchema,
+});
+
+export const GetSectionRequestSchema = strictObject({
+  sectionId: UuidSchema,
+});
+
+export const CreateSessionRequestSchema = strictObject({
+  assessmentSectionId: UuidSchema,
+  candidateId: z.string(),
+  demographics: z.record(z.string(), z.unknown()).optional(),
+});
+
+export const SubmitResultsRequestSchema = strictObject({
+  sessionId: UuidSchema,
+  result: AssessmentResultSchema,
+});
+
+export const EndSessionRequestSchema = strictObject({
+  sessionId: UuidSchema,
+  status: AssessmentResultTypeSchema.optional(),
+});
+
+export const EndSectionRequestSchema = strictObject({
+  sectionId: UuidSchema,
+});
+
+/**
+ * Response payloads for CAT operations
+ */
+
+export const CreateSectionResponseSchema = strictObject({
+  sectionId: UuidSchema,
+  status: z.literal("created"),
+});
+
+export const GetSectionResponseSchema = SectionDataSchema;
+
+export const CreateSessionResponseSchema = strictObject({
+  sessionId: UuidSchema,
+  status: z.literal("active"),
+});
+
+export const SubmitResultsResponseSchema = CatEngineResultReportSchema;
+
+export const EndSessionResponseSchema = strictObject({
+  sessionId: UuidSchema,
+  status: z.literal("ended"),
+  finalReport: CatEngineResultReportSchema.optional(),
+});
+
+export const EndSectionResponseSchema = strictObject({
+  sectionId: UuidSchema,
+  status: z.literal("ended"),
+});
+
+/**
+ * Error response
+ */
+export const ErrorResponseSchema = strictObject({
+  error: z.string(),
+  message: z.string(),
+  statusCode: z.number().int(),
+  details: z.record(z.string(), z.unknown()).optional(),
+});
+// Inferred types from exported Zod validators.
+export type Uuid = z.infer<typeof UuidSchema>;
+export type DateTime = z.infer<typeof DateTimeSchema>;
+export type ExtensionEnum = z.infer<typeof ExtensionEnumSchema>;
+export type OutcomeVariableType = z.infer<typeof OutcomeVariableTypeSchema>;
+export type OutcomeCardinality = z.infer<typeof OutcomeCardinalitySchema>;
+export type AssessmentResultType = z.infer<typeof AssessmentResultTypeSchema>;
+export type OutcomeVariable = z.infer<typeof OutcomeVariableSchema>;
+export type ResponseVariable = z.infer<typeof ResponseVariableSchema>;
+export type ItemRef = z.infer<typeof ItemRefSchema>;
+export type CatConstraint = z.infer<typeof CatConstraintSchema>;
+export type ItemPool = z.infer<typeof ItemPoolSchema>;
+export type SectionData = z.infer<typeof SectionDataSchema>;
+export type ItemStage = z.infer<typeof ItemStageSchema>;
+export type AssessmentResult = z.infer<typeof AssessmentResultSchema>;
+export type CatEngineResultReport = z.infer<typeof CatEngineResultReportSchema>;
+export type SessionInfo = z.infer<typeof SessionInfoSchema>;
+export type CreateSectionRequest = z.infer<typeof CreateSectionRequestSchema>;
+export type GetSectionRequest = z.infer<typeof GetSectionRequestSchema>;
+export type CreateSessionRequest = z.infer<typeof CreateSessionRequestSchema>;
+export type SubmitResultsRequest = z.infer<typeof SubmitResultsRequestSchema>;
+export type EndSessionRequest = z.infer<typeof EndSessionRequestSchema>;
+export type EndSectionRequest = z.infer<typeof EndSectionRequestSchema>;
+export type CreateSectionResponse = z.infer<typeof CreateSectionResponseSchema>;
+export type GetSectionResponse = z.infer<typeof GetSectionResponseSchema>;
+export type CreateSessionResponse = z.infer<typeof CreateSessionResponseSchema>;
+export type SubmitResultsResponse = z.infer<typeof SubmitResultsResponseSchema>;
+export type EndSessionResponse = z.infer<typeof EndSessionResponseSchema>;
+export type EndSectionResponse = z.infer<typeof EndSectionResponseSchema>;
+export type ErrorResponse = z.infer<typeof ErrorResponseSchema>;

package/src/clr/v2_0/clr_v2p0_achievementcredential_schema.ts

@@ -0,0 +1,16 @@
+export {
+  AchievementCredentialSchema,
+  AchievementSchema,
+  AchievementSubjectSchema,
+  AchievementTypeSchema,
+  AlignmentSchema,
+  AlignmentTargetTypeSchema,
+  CriteriaSchema,
+  IdentityObjectSchema,
+  RelatedSchema,
+  ResultDescriptionSchema,
+  ResultSchema,
+  ResultStatusTypeSchema,
+  ResultTypeSchema,
+  RubricCriterionLevelSchema,
+} from "./shared";

package/src/clr/v2_0/clr_v2p0_clrcredential_schema.ts

@@ -0,0 +1,9 @@
+export {
+  AssociationSchema,
+  AssociationTypeSchema,
+  ClrCredentialSchema,
+  ClrSubjectSchema,
+  CredentialSubjectSchema,
+  IdentityObjectSchema,
+  VerifiableCredentialSchema,
+} from "./shared";

package/src/clr/v2_0/clr_v2p0_endorsementcredential_schema.ts

@@ -0,0 +1,11 @@
+export {
+  CredentialSchemaSchema,
+  CredentialStatusSchema,
+  EndorsementCredentialSchema,
+  EndorsementSubjectSchema,
+  EvidenceSchema,
+  ProfileRefSchema,
+  ProofSchema,
+  RefreshServiceSchema,
+  TermsOfUseSchema,
+} from "./shared";

package/src/clr/v2_0/clr_v2p0_getclrcredentialsresponse_schema.ts

@@ -0,0 +1 @@
+export { GetClrCredentialsResponseSchema } from "./shared";

package/src/clr/v2_0/clr_v2p0_imsx_statusinfo_schema.ts

@@ -0,0 +1,8 @@
+export {
+  ImsxCodeMajorSchema,
+  ImsxCodeMinorFieldSchema,
+  ImsxCodeMinorFieldValueSchema,
+  ImsxCodeMinorSchema,
+  ImsxSeveritySchema,
+  ImsxStatusInfoSchema,
+} from "../../shared/imsx-status";

package/src/clr/v2_0/clr_v2p0_profile_schema.ts

@@ -0,0 +1,9 @@
+export {
+  AddressSchema,
+  GeoCoordinatesSchema,
+  IdentifierEntrySchema,
+  IdentifierTypeEnumSchema,
+  ImageSchema,
+  ProfileRefSchema,
+  ProfileSchema,
+} from "./shared";

package/src/clr/v2_0/index.ts

@@ -0,0 +1,22 @@
+export * from "./clr_v2p0_clrcredential_schema";
+export * from "./clr_v2p0_achievementcredential_schema";
+export * from "./clr_v2p0_endorsementcredential_schema";
+export * from "./clr_v2p0_profile_schema";
+export * from "./clr_v2p0_getclrcredentialsresponse_schema";
+export * from "./clr_v2p0_imsx_statusinfo_schema";
+
+import { AchievementCredentialSchema } from "./clr_v2p0_achievementcredential_schema";
+import { ClrCredentialSchema } from "./clr_v2p0_clrcredential_schema";
+import { EndorsementCredentialSchema } from "./clr_v2p0_endorsementcredential_schema";
+import { GetClrCredentialsResponseSchema } from "./clr_v2p0_getclrcredentialsresponse_schema";
+import { ImsxStatusInfoSchema } from "./clr_v2p0_imsx_statusinfo_schema";
+import { ProfileSchema } from "./clr_v2p0_profile_schema";
+
+export const Clr20DerivedZodTemplates = {
+  clrCredential: ClrCredentialSchema,
+  achievementCredential: AchievementCredentialSchema,
+  endorsementCredential: EndorsementCredentialSchema,
+  getClrCredentialsResponse: GetClrCredentialsResponseSchema,
+  profile: ProfileSchema,
+  imsxStatusInfo: ImsxStatusInfoSchema,
+} as const;

package/src/clr/v2_0/shared.ts

@@ -0,0 +1,206 @@
+import { z } from "zod";
+
+import {
+  AchievementCredentialSchema,
+  AchievementSchema,
+  AchievementSubjectSchema,
+  AchievementTypeSchema,
+  AddressSchema,
+  AlignmentSchema,
+  AlignmentTargetTypeSchema,
+  CriteriaSchema,
+  CredentialSubjectSchema,
+  CredentialSchemaSchema,
+  CredentialStatusSchema,
+  EndorsementCredentialSchema,
+  EndorsementSubjectSchema,
+  EvidenceSchema,
+  GeoCoordinatesSchema,
+  IdentifierEntrySchema,
+  IdentifierTypeEnumSchema,
+  IdentityObjectSchema,
+  ImageSchema,
+  OpenBadgesV30ContextUrlSchema,
+  ProfileRefSchema,
+  ProfileSchema,
+  ProofSchema,
+  RefreshServiceSchema,
+  RelatedSchema,
+  ResultDescriptionSchema,
+  ResultSchema,
+  ResultStatusTypeSchema,
+  ResultTypeSchema,
+  RubricCriterionLevelSchema,
+  TermsOfUseSchema,
+} from "../../open-badges/v3_0/shared";
+import {
+  CompactJwsValueSchema,
+  contextArraySchema,
+  credentialTypeSchema,
+  oneOrMany,
+  type OneOrManyValue,
+  passthroughObject,
+  singleTypeSchema,
+  TextValueSchema,
+  type TextValue,
+  UriValueSchema,
+  type UriValue,
+  W3cCredentialsV2ContextSchema,
+} from "../../vc-data-model/v2_0/shared";
+
+type ClrSubject = {
+  id?: UriValue;
+  type: unknown;
+  identifier?: OneOrManyValue<Record<string, unknown>>;
+  achievement?: OneOrManyValue<Record<string, unknown>>;
+  verifiableCredential: OneOrManyValue<Record<string, unknown>>;
+  association?: OneOrManyValue<Record<string, unknown>>;
+  [key: string]: unknown;
+};
+
+type ClrCredential = {
+  "@context": Array<Record<string, unknown> | UriValue>;
+  type: unknown;
+  id: UriValue;
+  name: TextValue;
+  description?: TextValue;
+  endorsement?: OneOrManyValue<Record<string, unknown>>;
+  endorsementJwt?: OneOrManyValue<string | Record<string, string>>;
+  image?: Record<string, unknown>;
+  partial?: boolean;
+  credentialSubject: ClrSubject;
+  awardedDate?: string;
+  issuer: UriValue | Record<string, unknown>;
+  validFrom: string;
+  validUntil?: string;
+  proof?: OneOrManyValue<Record<string, unknown>>;
+  credentialSchema?: OneOrManyValue<Record<string, unknown>>;
+  credentialStatus?: Record<string, unknown>;
+  refreshService?: Record<string, unknown>;
+  termsOfUse?: OneOrManyValue<Record<string, unknown>>;
+  evidence?: OneOrManyValue<Record<string, unknown>>;
+  [key: string]: unknown;
+};
+
+const ClrV20ContextUrlSchema = z
+  .string()
+  .regex(/^https:\/\/purl\.imsglobal\.org\/spec\/clr\/v2p0\/context(-2\.\d\.\d)*\.json$/u);
+
+const ClrCredentialContextSchema = contextArraySchema("CLR 2.0", [
+  W3cCredentialsV2ContextSchema,
+  ClrV20ContextUrlSchema,
+  OpenBadgesV30ContextUrlSchema,
+]);
+
+export const AssociationTypeSchema = z.enum([
+  "exactMatchOf",
+  "isChildOf",
+  "isParentOf",
+  "isPartOf",
+  "isPeerOf",
+  "isRelatedTo",
+  "precedes",
+  "replacedBy",
+]);
+
+export const AssociationSchema = passthroughObject({
+  type: singleTypeSchema("Association"),
+  associationType: AssociationTypeSchema,
+  sourceId: UriValueSchema,
+  targetId: UriValueSchema,
+});
+
+export const VerifiableCredentialSchema = passthroughObject({
+  "@context": contextArraySchema("CLR 2.0", [W3cCredentialsV2ContextSchema]),
+  id: UriValueSchema.optional(),
+  type: singleTypeSchema("VerifiableCredential"),
+  issuer: ProfileRefSchema,
+  validFrom: z.iso.datetime(),
+  validUntil: z.iso.datetime().optional(),
+  credentialSubject: passthroughObject({
+    id: UriValueSchema.optional(),
+  }),
+  proof: oneOrMany(ProofSchema).optional(),
+  credentialSchema: oneOrMany(CredentialSchemaSchema).optional(),
+  credentialStatus: CredentialStatusSchema.optional(),
+  refreshService: RefreshServiceSchema.optional(),
+  termsOfUse: oneOrMany(TermsOfUseSchema).optional(),
+  evidence: oneOrMany(EvidenceSchema).optional(),
+});
+
+export const ClrSubjectSchema: z.ZodType<ClrSubject> = passthroughObject({
+  id: UriValueSchema.optional(),
+  type: singleTypeSchema("ClrSubject"),
+  identifier: oneOrMany(IdentityObjectSchema).optional(),
+  achievement: oneOrMany(AchievementSchema).optional(),
+  verifiableCredential: oneOrMany(VerifiableCredentialSchema),
+  association: oneOrMany(AssociationSchema).optional(),
+});
+
+export const ClrCredentialSchema: z.ZodType<ClrCredential> = passthroughObject({
+  "@context": ClrCredentialContextSchema,
+  type: credentialTypeSchema(["ClrCredential"]),
+  id: UriValueSchema,
+  name: TextValueSchema,
+  description: TextValueSchema.optional(),
+  endorsement: oneOrMany(EndorsementCredentialSchema).optional(),
+  endorsementJwt: oneOrMany(CompactJwsValueSchema).optional(),
+  image: ImageSchema.optional(),
+  partial: z.boolean().optional(),
+  credentialSubject: ClrSubjectSchema,
+  awardedDate: z.iso.datetime().optional(),
+  issuer: ProfileRefSchema,
+  validFrom: z.iso.datetime(),
+  validUntil: z.iso.datetime().optional(),
+  proof: oneOrMany(ProofSchema).optional(),
+  credentialSchema: oneOrMany(CredentialSchemaSchema).optional(),
+  credentialStatus: CredentialStatusSchema.optional(),
+  refreshService: RefreshServiceSchema.optional(),
+  termsOfUse: oneOrMany(TermsOfUseSchema).optional(),
+  evidence: oneOrMany(EvidenceSchema).optional(),
+});
+
+export const GetClrCredentialsResponseSchema = z
+  .object({
+    credential: oneOrMany(ClrCredentialSchema).optional(),
+    compactJwsString: oneOrMany(CompactJwsValueSchema).optional(),
+  })
+  .strict();
+
+export {
+  AchievementCredentialSchema,
+  AchievementSchema,
+  AchievementSubjectSchema,
+  AchievementTypeSchema,
+  AddressSchema,
+  AlignmentSchema,
+  AlignmentTargetTypeSchema,
+  CriteriaSchema,
+  CredentialSubjectSchema,
+  CredentialSchemaSchema,
+  CredentialStatusSchema,
+  EndorsementCredentialSchema,
+  EndorsementSubjectSchema,
+  EvidenceSchema,
+  GeoCoordinatesSchema,
+  IdentifierEntrySchema,
+  IdentifierTypeEnumSchema,
+  IdentityObjectSchema,
+  ImageSchema,
+  ProfileRefSchema,
+  ProfileSchema,
+  ProofSchema,
+  RefreshServiceSchema,
+  RelatedSchema,
+  ResultDescriptionSchema,
+  ResultSchema,
+  ResultStatusTypeSchema,
+  ResultTypeSchema,
+  RubricCriterionLevelSchema,
+  TermsOfUseSchema,
+};
+// Inferred types from exported Zod validators.
+export type AssociationType = z.infer<typeof AssociationTypeSchema>;
+export type Association = z.infer<typeof AssociationSchema>;
+export type VerifiableCredential = z.infer<typeof VerifiableCredentialSchema>;
+export type GetClrCredentialsResponse = z.infer<typeof GetClrCredentialsResponseSchema>;

package/src/cmi5/index.ts

@@ -0,0 +1,3 @@
+export * from "./v1_0";
+
+export * as V1_0 from "./v1_0";