@common-grants/core 0.1.1 → 0.2.0-alpha.1

package/lib/api.tsp

@@ -2,9 +2,11 @@
 import "./core/index.tsp";
 import "@typespec/http";
 import "@typespec/openapi";
+import "@typespec/versioning";
 
 using TypeSpec.Http;
 using TypeSpec.OpenAPI;
+using Versioning;
 
 /** The base OpenAPI specification for a CommonGrants API
  *
@@ -12,6 +14,12 @@ using TypeSpec.OpenAPI;
  * it must implement all of the routes with the "required" tag in this specification.
  */
 @service(#{ title: "CommonGrants Base API" })
+@tagMetadata(
+  "experimental",
+  #{
+    description: "Endpoints that MAY be implemented by CommonGrants APIs, but are not guaranteed to be stable",
+  }
+)
 @tagMetadata(
   "optional",
   #{ description: "Endpoints that MAY be implemented by CommonGrants APIs" }
@@ -22,12 +30,22 @@ using TypeSpec.OpenAPI;
     description: "Endpoints that MUST be implemented by all CommonGrants APIs",
   }
 )
+@tagMetadata(
+  "Applications",
+  #{
+    description: "Endpoints related to applications for funding opportunities",
+  }
+)
 @tagMetadata(
   "Opportunities",
   #{ description: "Endpoints related to funding opportunities" }
 )
 namespace CommonGrants.API;
 
+// #########################################################
+// Opportunities
+// #########################################################
+
 @tag("Opportunities")
 @route("/common-grants/opportunities")
 namespace Opportunities {
@@ -42,3 +60,64 @@ namespace Opportunities {
   @tag("optional")
   op search is Router.search;
 }
+
+// #########################################################
+// Applications
+// #########################################################
+
+@tag("Applications")
+@tag("experimental")
+@route("/common-grants/")
+namespace Apply {
+  // #########################################################
+  // Direct apply workflow
+  // #########################################################
+  @tag("experimental")
+  @route("/competitions")
+  namespace DirectApplyWorkflow {
+    alias Router = Routes.Competitions;
+
+    @added(Versions.v0_2)
+    op competitionDetails is Router.read;
+
+    @added(Versions.v0_2)
+    op apply is Router.apply;
+  }
+
+  // #########################################################
+  // Multi-step workflow
+  // #########################################################
+
+  @route("/applications")
+  namespace MultiStepWorkflow {
+    alias ApplicationRouter = Routes.Applications;
+    alias FormResponseRouter = Routes.FormResponses;
+
+    // ################################
+    // Start an application workflow
+    // ################################
+
+    @added(Versions.v0_2)
+    op startApplication is ApplicationRouter.startApplication;
+
+    @added(Versions.v0_2)
+    op getApplication is ApplicationRouter.getApplication;
+
+    // ################################
+    // Update form responses
+    // ################################
+
+    @added(Versions.v0_2)
+    op setFormResponse is FormResponseRouter.setFormResponse;
+
+    @added(Versions.v0_2)
+    op getFormResponse is FormResponseRouter.getFormResponse;
+
+    // ################################
+    // Submit an application after completing all forms
+    // ################################
+
+    @added(Versions.v0_2)
+    op submitApplication is ApplicationRouter.submitApplication;
+  }
+}

package/lib/core/fields/custom-field.tsp

@@ -76,6 +76,13 @@ namespace Examples.CustomField {
     schema: "https://example.com/program-areas.json",
   };
 
+  const agency = #{
+    name: "agency",
+    fieldType: CustomFieldType.string,
+    value: "Department of Transportation",
+    description: "The agency responsible for managing this opportunity",
+  };
+
   /** An example of an array custom field */
   const eligibilityTypes = #{
     name: "eligibilityType",

package/lib/core/fields/file.tsp

@@ -0,0 +1,49 @@
+namespace CommonGrants.Fields;
+
+/** A field representing a downloadable file. */
+@example(Examples.File.imageFile, #{ title: "An image file" })
+@example(Examples.File.pdfFile, #{ title: "A PDF file" })
+model File {
+  /** The file's download URL. */
+  downloadUrl: url;
+
+  /** The file's name. */
+  name: string;
+
+  /** The file's description. */
+  description?: string;
+
+  /** The file's size in bytes. */
+  sizeInBytes?: numeric;
+
+  /** The file's MIME type. */
+  mimeType?: string;
+
+  /** The system metadata for the file. */
+  ...Fields.SystemMetadata;
+}
+
+// #########################################################
+// Examples
+// #########################################################
+
+namespace Examples.File {
+  const pdfFile = #{
+    downloadUrl: "https://example.com/file.pdf",
+    name: "example.pdf",
+    description: "A PDF file with instructions",
+    sizeInBytes: 1000,
+    mimeType: "application/pdf",
+    createdAt: utcDateTime.fromISO("2025-01-01T17:01:01"),
+    lastModifiedAt: utcDateTime.fromISO("2025-01-02T17:30:00"),
+  };
+
+  const imageFile = #{
+    downloadUrl: "https://example.com/image.png",
+    name: "image.png",
+    sizeInBytes: 1000,
+    mimeType: "image/png",
+    createdAt: utcDateTime.fromISO("2025-01-01T17:01:01"),
+    lastModifiedAt: utcDateTime.fromISO("2025-01-02T17:30:00"),
+  };
+}

package/lib/core/fields/index.tsp

@@ -7,6 +7,7 @@ import "./name.tsp";
 import "./phone.tsp";
 import "./pcs.tsp";
 import "./email.tsp";
+import "./file.tsp";
 
 using TypeSpec.JsonSchema;
 

package/lib/core/models/application.tsp

@@ -1,33 +1,29 @@
-import "../index.tsp";
-
 namespace CommonGrants.Models;
 
-/** The base model for an application. */
-@example(Examples.Application.exampleApplication)
 model ApplicationBase {
-  /** The application's unique identifier. */
+  /** The unique identifier for the application */
   id: Types.uuid;
 
-  /** The application's status. */
-  status?: AppStatus;
-
-  /** The application's date of submission. */
-  dateSubmitted?: Types.isoDate;
+  /** The name of the application */
+  name: string;
 
-  /** The organization that is applying for the grant. */
-  organization?: OrganizationBase;
+  /** The unique identifier for the competition */
+  competitionId: Types.uuid;
 
-  /** The person who is applying for the grant. */
-  pointOfContact?: PersonBase;
+  /** The form responses for the application */
+  formResponses: Record<AppFormResponse>;
 
-  /** The application's proposal for funding. */
-  proposal?: AppProposal;
+  /** The status of the application */
+  status: AppStatus;
 
-  /** The opportunity being applied to. */
-  opportunity?: AppOpportunity;
+  /** The date and time the application was submitted */
+  submittedAt?: utcDateTime | null;
 
-  /** The application's custom fields. */
+  /** The custom fields about the application */
   customFields?: Record<Fields.CustomField>;
+
+  /** The system metadata for the application */
+  ...Fields.SystemMetadata;
 }
 
 // #########################################################
@@ -53,52 +49,29 @@ model AppStatus {
 
 /** The default set of values accepted for application status. */
 enum AppStatusOptions {
-  submitted,
-  approved,
-  rejected,
-  custom,
-}
+  /** The application is a draft */
+  draft,
 
-// #########################################################
-// AppProject
-// #########################################################
-
-/** The project for which funding is requested. */
-@example(Examples.Application.exampleProposal)
-model AppProposal {
-  /** The title of the proposal and/or the project requesting funding. */
-  title: string;
-
-  /** The description of the proposal and/or the project requesting funding. */
-  description: string;
-
-  /** The amount of money requested. */
-  amountRequested?: Fields.Money;
+  /** The application has been submitted */
+  submitted,
 
-  /** The start date of the period for which the funding is requested. */
-  periodStartDate?: Types.isoDate;
+  /** The application has been accepted */
+  accepted,
 
-  /** The end date of the period for which the funding is requested. */
-  periodEndDate?: Types.isoDate;
+  /** The application has been rejected */
+  rejected,
 
-  /** The project's custom fields. */
-  customFields?: Record<Fields.CustomField>;
+  /** The application has a custom status */
+  custom,
 }
 
 // #########################################################
-// AppOpportunity
+// ApplicationFormResponse
 // #########################################################
 
-/** The opportunity to which this application is related */
-model AppOpportunity {
-  /** The opportunity's unique identifier. */
-  id: Types.uuid;
-
-  /** The opportunity's name. */
-  title?: string;
-
-  /** The opportunity's custom fields. */
-  customFields?: Record<Fields.CustomField>;
+model AppFormResponse extends FormResponseBase {
+  /** The unique identifier for the application */
+  applicationId: Types.uuid;
 }
 
 // #########################################################
@@ -106,19 +79,9 @@ model AppOpportunity {
 // #########################################################
 
 namespace Examples.Application {
-  const exampleApplication = #{
-    id: "083b4567-e89d-42c8-a439-6c1234567890",
-    status: submittedStatus,
-    dateSubmitted: Types.isoDate.fromISO("2024-01-01"),
-    organization: Examples.Organization.exampleOrg,
-    pointOfContact: Examples.Person.examplePerson,
-    proposal: exampleProposal,
-    opportunity: exampleOpportunity,
-  };
-
   const submittedStatus = #{
     value: AppStatusOptions.submitted,
-    description: "Application has been submitted.",
+    description: "The application has been submitted.",
   };
 
   const customStatus = #{
@@ -126,17 +89,4 @@ namespace Examples.Application {
     customValue: "draft",
     description: "Application is started but not yet submitted.",
   };
-
-  const exampleProposal = #{
-    title: "Example Project",
-    description: "Example project to serve community needs.",
-    amountRequested: #{ amount: "100000", currency: "USD" },
-    periodStartDate: Types.isoDate.fromISO("2024-01-01"),
-    periodEndDate: Types.isoDate.fromISO("2024-12-31"),
-  };
-
-  const exampleOpportunity = #{
-    id: "083b4567-e89d-42c8-a439-6c1234567890",
-    title: "Example Opportunity",
-  };
 }

package/lib/core/models/competition.tsp

@@ -0,0 +1,148 @@
+namespace CommonGrants.Models;
+
+/**
+ * The base model for a competition.
+ *
+ * A competition is an application process for a funding opportunity. It often has a
+ * distinct application period and set of application forms.
+ */
+@example(Examples.Competition.competition)
+model CompetitionBase {
+  /** Globally unique id for the competition */
+  id: Types.uuid;
+
+  /** The opportunity id for the competition */
+  opportunityId: Types.uuid;
+
+  /** The title of the competition */
+  title: string;
+
+  /** The description of the competition */
+  description?: string;
+
+  /** The instructions for the competition */
+  instructions?: string | Fields.File;
+
+  /** The status of the competition */
+  status: CompetitionStatus;
+
+  /** The key dates in the competition timeline */
+  keyDates: CompetitionTimeline;
+
+  /** The forms for the competition */
+  forms: CompetitionForms;
+
+  /** The custom fields for the competition */
+  customFields?: Record<Fields.CustomField>;
+
+  /** The system metadata for the competition */
+  ...Fields.SystemMetadata;
+}
+
+// #########################################################
+// CompetitionStatus
+// #########################################################
+
+/** The status of the competition */
+@example(Examples.Competition.status)
+model CompetitionStatus {
+  value: CompetitionStatusOptions;
+  customValue?: string;
+  description?: string;
+}
+
+// #########################################################
+// CompetitionStatusOptions
+// #########################################################
+
+enum CompetitionStatusOptions {
+  /** The competition is open for applications */
+  open,
+
+  /** The competition is closed for applications */
+  closed,
+
+  /** The competition is in a custom status */
+  custom,
+}
+
+// #########################################################
+// CompetitionForm
+// #########################################################
+
+/** Set of forms that need to be completed to apply to the competition. */
+@example(Examples.Competition.forms)
+model CompetitionForms {
+  /** The forms for the competition */
+  forms: Record<Models.Form>;
+
+  /** The validation rules for the competition forms */
+  validation: Record<unknown>;
+}
+
+// #########################################################
+// CompetitionTimeline
+// #########################################################
+
+@example(Examples.Competition.keyDates)
+model CompetitionTimeline {
+  /** The start date of the competition */
+  openDate: Fields.Event;
+
+  /** The end date of the competition */
+  closeDate: Fields.Event;
+
+  /** The date the competition was created */
+  otherDates?: Record<Fields.Event>;
+}
+
+// #########################################################
+// Examples
+// #########################################################
+
+namespace Examples.Competition {
+  const competition = #{
+    id: "b7c1e2f4-8a3d-4e2a-9c5b-1f2e3d4c5b6a",
+    opportunityId: "b7c1e2f4-8a3d-4e2a-9c5b-1f2e3d4c5b6b",
+    title: "Competition 1",
+    description: "Competition 1 description",
+    instructions: "Competition 1 instructions",
+    status: status,
+    keyDates: keyDates,
+    forms: forms,
+    createdAt: utcDateTime.fromISO("2025-01-01T00:00:00Z"),
+    lastModifiedAt: utcDateTime.fromISO("2025-01-01T00:00:00Z"),
+  };
+
+  const keyDates = #{
+    openDate: #{
+      name: "Open Date",
+      eventType: Fields.EventType.singleDate,
+      date: Types.isoDate.fromISO("2025-01-01"),
+    },
+    closeDate: #{
+      name: "Close Date",
+      eventType: Fields.EventType.singleDate,
+      date: Types.isoDate.fromISO("2025-01-30"),
+    },
+    otherDates: #{
+      reviewPeriod: #{
+        name: "Application Review Period",
+        eventType: Fields.EventType.dateRange,
+        startDate: Types.isoDate.fromISO("2025-02-01"),
+        endDate: Types.isoDate.fromISO("2025-02-28"),
+      },
+    },
+  };
+
+  const status = #{
+    value: CompetitionStatusOptions.open,
+    customValue: "custom",
+    description: "Competition is open for applications",
+  };
+
+  const forms = #{
+    forms: #{ formA: Examples.Form.form, formB: Examples.Form.form },
+    validation: #{ required: #["formA", "formB"] },
+  };
+}

package/lib/core/models/form-response.tsp

@@ -0,0 +1,71 @@
+namespace CommonGrants.Models;
+
+/** The base model for a form response */
+model FormResponseBase {
+  /** The unique identifier for the form response */
+  id: Types.uuid;
+
+  /** The form being responded to */
+  form: Form;
+
+  /** The response to the form */
+  response: Record<unknown>;
+
+  /** The status of the form response */
+  status: FormResponseStatus;
+
+  /** The validation errors for the form response */
+  validationErrors: Array<unknown>;
+
+  /** The system metadata for the form response */
+  ...Fields.SystemMetadata;
+}
+
+// #########################################################
+// FormResponseStatus
+// #########################################################
+
+/** The status of the form response */
+@example(Examples.FormResponse.inProgressStatus)
+model FormResponseStatus {
+  /** The status of the form response */
+  value: FormResponseStatusOptions;
+
+  /** A custom value for the status */
+  customValue?: string;
+
+  /** A description of the status */
+  description?: string;
+}
+
+// #########################################################
+// FormResponseStatusOptions
+// #########################################################
+
+/** The options for the status of the form response */
+enum FormResponseStatusOptions {
+  /** The form response has not been started */
+  notStarted,
+
+  /** The form response is in progress */
+  inProgress,
+
+  /** The form response is submitted */
+  complete,
+}
+
+// #########################################################
+// Examples
+// #########################################################
+
+namespace Examples.FormResponse {
+  const inProgressStatus = #{
+    value: FormResponseStatusOptions.inProgress,
+    description: "The form response is in progress",
+  };
+
+  const completeStatus = #{
+    value: FormResponseStatusOptions.complete,
+    description: "The form response is complete",
+  };
+}

package/lib/core/models/form.tsp

@@ -0,0 +1,119 @@
+import "../index.tsp";
+
+namespace CommonGrants.Models;
+
+// #########################################################
+// Form
+// #########################################################
+
+/** A form for collecting data from a user. */
+@example(Examples.Form.form)
+model Form {
+  /** The form's unique identifier. */
+  id: Types.uuid;
+
+  /** The form's name. */
+  name: string;
+
+  /** The form's description. */
+  description?: string;
+
+  /** The form's instructions. */
+  instructions?: string | Fields.File;
+
+  /** The form's JSON schema used to render the form and validate responses. */
+  jsonSchema?: FormJsonSchema;
+
+  /** The form's UI schema used to render the form in the browser. */
+  uiSchema?: FormUISchema;
+
+  /** A mapping from form schema to CommonGrants schema. */
+  mappingToCommonGrants?: Models.MappingSchema;
+
+  /** A mapping from CommonGrants schema to form schema. */
+  mappingFromCommonGrants?: Models.MappingSchema;
+
+  /** Custom attributes about the form itself, not custom fields within the form. */
+  customFields?: Record<Fields.CustomField>;
+}
+
+// #########################################################
+// FormJsonSchema
+// #########################################################
+
+/** A JSON schema used to validate form responses. */
+@example(Examples.Form.formSchema)
+model FormJsonSchema {
+  ...Record<unknown>;
+}
+
+// #########################################################
+// FormUISchema
+// #########################################################
+
+/** A UI schema used to render the form in the browser. */
+@example(Examples.Form.uiSchema)
+model FormUISchema {
+  ...Record<unknown>;
+}
+
+// #########################################################
+// Examples
+// #########################################################
+
+namespace Examples.Form {
+  const form = #{
+    id: "b7c1e2f4-8a3d-4e2a-9c5b-1f2e3d4c5b6a",
+    name: "Form A",
+    description: "Form A description",
+    instructions: "Form A instructions",
+    jsonSchema: formSchema,
+    uiSchema: uiSchema,
+    mappingToCommonGrants: mappingToCommonGrants,
+    mappingFromCommonGrants: mappingFromCommonGrants,
+  };
+
+  const formSchema = #{
+    $id: "formA.json",
+    type: "object",
+    properties: #{
+      name: #{ first: #{ type: "string" }, last: #{ type: "string" } },
+      email: #{ type: "string" },
+      phone: #{ type: "string" },
+    },
+  };
+
+  const uiSchema = #{
+    type: "VerticalLayout",
+    elements: #[
+      #{
+        type: "Group",
+        label: "Name",
+        elements: #[
+          #{ type: "Control", scope: "#/properties/name/first" },
+          #{ type: "Control", scope: "#/properties/name/last" }
+        ],
+      },
+      #{ type: "Control", scope: "#/properties/email" },
+      #{ type: "Control", scope: "#/properties/phone" }
+    ],
+  };
+
+  const mappingToCommonGrants = #{
+    name: #{
+      firstName: #{ field: "name.first" },
+      lastName: #{ field: "name.last" },
+    },
+    emails: #{ primary: #{ field: "email" } },
+    phones: #{ primary: #{ field: "phone" } },
+  };
+
+  const mappingFromCommonGrants = #{
+    name: #{
+      first: #{ field: "name.firstName" },
+      last: #{ field: "name.lastName" },
+    },
+    email: #{ field: "emails.primary" },
+    phone: #{ field: "phones.primary" },
+  };
+}

package/lib/core/models/index.tsp

@@ -5,7 +5,12 @@ import "@typespec/json-schema";
 import "./opportunity/index.tsp";
 import "./organization.tsp";
 import "./person.tsp";
+import "./proposal.tsp";
 import "./application.tsp";
+import "./competition.tsp";
+import "./form.tsp";
+import "./form-response.tsp";
+import "./mapping.tsp";
 
 using TypeSpec.JsonSchema;
 

package/lib/core/models/mapping.tsp

@@ -0,0 +1,162 @@
+namespace CommonGrants.Models;
+
+// #########################################################
+// Mapping
+// #########################################################
+
+/** A mapping schema for translating data from one schema to another.
+ *
+ * Example:
+ *
+ * The following mapping:
+ *
+ * ```json
+ * {
+ *   "id": { "const": "123" },
+ *   "opportunity": {
+ *     "status": {
+ *       "switch": {
+ *         "field": "opportunity_status",
+ *         "case": { "active": "open", "inactive": "closed" },
+ *         "default": "custom",
+ *       },
+ *     },
+ *     "amount": { "field": "opportunity_amount" },
+ *   }
+ * }
+ * ```
+ *
+ * Will translate the following data:
+ *
+ * ```json
+ * {
+ *   "id": "123",
+ *   "opportunity_status": "active",
+ *   "opportunity_amount": 100,
+ * }
+ * ```
+ *
+ * To the following data:
+ *
+ * ```json
+ * {
+ *   "id": "123",
+ *   "opportunity": { "status": "open", "amount": 100 },
+ * }
+ */
+@example(Examples.Mapping.flatRenaming)
+@example(Examples.Mapping.nestedRenaming)
+@example(Examples.Mapping.simpleSwitch)
+@example(Examples.Mapping.nestedSwitch)
+@example(Examples.Mapping.withLiteralValues)
+model MappingSchema {
+  ...Record<MappingFunction | unknown>;
+}
+
+// #########################################################
+// MappingFunctions
+// #########################################################
+
+/** The set of supported mapping functions. */
+union MappingFunction {
+  `const`: MappingConstantFunction,
+  field: MappingFieldFunction,
+  switch: MappingSwitchFunction,
+}
+
+// #########################################################
+// MappingLiteralFunction
+// #########################################################
+
+/** Returns a constant value. */
+model MappingConstantFunction {
+  `const`: unknown;
+}
+
+// #########################################################
+// MappingFieldFunction
+// #########################################################
+
+/** Returns the value of a field in the source data. */
+model MappingFieldFunction {
+  field: string;
+}
+
+// #########################################################
+// MappingSwitchFunction
+// #########################################################
+
+/** Returns a new value based on the value of a field in the source data using a switch statement. */
+model MappingSwitchFunction {
+  /** The field in the source data to switch on. */
+  field: string;
+
+  /** An object mapping source field values to desired output values. */
+  case: Record<unknown>;
+
+  /** The default value to output if no case matches the source field value. */
+  default?: unknown;
+}
+
+// #########################################################
+// Examples
+// #########################################################
+
+namespace Examples.Mapping {
+  const flatRenaming = #{
+    opportunityStatus: #{ field: "opportunity_status" },
+    opportunityAmount: #{ field: "opportunity_amount" },
+  };
+
+  const nestedRenaming = #{
+    id: #{ field: "opportunity_id" },
+    opportunity: #{
+      status: #{ field: "opportunity_status" },
+      amount: #{ field: "opportunity_amount" },
+    },
+  };
+
+  const simpleSwitch = #{
+    opportunityAmount: #{ field: "opportunity_amount" },
+    opportunityStatus: #{
+      switch: #{
+        field: "opportunity_status",
+        case: #{ active: "open", inactive: "closed" },
+        default: "custom",
+      },
+    },
+  };
+
+  const nestedSwitch = #{
+    opportunity: #{
+      status: #{
+        switch: #{
+          field: "opportunity_status",
+          case: #{ active: "open", inactive: "closed" },
+          default: "custom",
+        },
+        amount: #{ field: "opportunity_amount" },
+      },
+    },
+  };
+
+  const withLiteralValues = #{
+    id: #{ `const`: "123" },
+    opportunity: #{
+      status: #{
+        switch: #{
+          field: "opportunity_status",
+          case: #{ active: "open", inactive: "closed" },
+          default: "custom",
+        },
+      },
+      amount: #{ field: "opportunity_amount" },
+    },
+  };
+
+  const formToCommonGrants = #{
+    name: #{ field: "name" },
+    email: #{ field: "email" },
+    phone: #{ field: "phone" },
+  };
+}

package/lib/core/models/proposal.tsp

@@ -0,0 +1,173 @@
+namespace CommonGrants.Models;
+
+// #########################################################
+// ProposalBase
+// #########################################################
+
+/** A proposal for funding. */
+@example(Examples.Proposal.exampleProposal)
+model ProposalBase {
+  /** The title of the proposal and/or the project requesting funding. */
+  title?: string;
+
+  /** The description of the proposal and/or the project requesting funding. */
+  description?: string;
+
+  /** The amount of money requested. */
+  amountRequested?: Fields.Money;
+
+  /** The key dates for the project. */
+  projectTimeline?: ProjectTimeline;
+
+  /** The opportunity to which this proposal is related */
+  opportunity?: ProposalOpportunity;
+
+  /** The organization that is requesting funding. */
+  organizations?: ProposalOrgs;
+
+  /** The point of contact for the project. */
+  contacts?: ProposalContacts;
+
+  /** The project's custom fields. */
+  customFields?: Record<Fields.CustomField>;
+}
+
+// #########################################################
+// ProposalOpportunity
+// #########################################################
+
+/** The opportunity to which this proposal is related */
+model ProposalOpportunity {
+  /** The opportunity's unique identifier. */
+  id: Types.uuid;
+
+  /** The opportunity's name. */
+  title?: string;
+
+  /** The opportunity's custom fields. */
+  customFields?: Record<Fields.CustomField>;
+}
+
+// #########################################################
+// ProjectTimeline
+// #########################################################
+
+model ProjectTimeline {
+  /** The start date of the period for which the funding is requested. */
+  startDate?: Fields.Event;
+
+  /** The end date of the period for which the funding is requested. */
+  endDate?: Fields.Event;
+
+  /** The key dates for the project. */
+  otherDates?: Record<Fields.Event>;
+
+  /** Details about the timeline that don't fit into the other fields. */
+  timelineDetails?: string;
+}
+
+// #########################################################
+// ProjectContacts
+// #########################################################
+
+model ProposalContacts {
+  /** The primary point of contact for the proposal. */
+  primary: PersonBase;
+
+  /** Other points of contact for the proposal. For example, key personnel, authorized representatives, etc. */
+  otherContacts?: Record<PersonBase>;
+}
+
+// #########################################################
+// ProposalOrgs
+// #########################################################
+
+model ProposalOrgs {
+  /** The primary organization that is requesting funding. */
+  primary: OrganizationBase;
+
+  /** Other organizations that are supporting the proposal. For example, a fiscal sponsor, partners, etc. */
+  otherOrgs?: Record<OrganizationBase>;
+}
+
+// #########################################################
+// Examples
+// #########################################################
+
+namespace Examples.Proposal {
+  const exampleProposal = #{
+    title: "Example Project",
+    description: "Example project to serve community needs.",
+    amountRequested: #{ amount: "100000", currency: "USD" },
+    opportunity: exampleOpportunity,
+    projectTimeline: timeline,
+    contacts: contacts,
+    organizations: organizations,
+  };
+
+  // #####################################
+  // Opportunity
+  // #####################################
+
+  const exampleOpportunity = #{
+    id: "083b4567-e89d-42c8-a439-6c1234567890",
+    title: "Example Opportunity",
+    customFields: #{ agency: Fields.Examples.CustomField.agency },
+  };
+
+  // #####################################
+  // ProjectTimeline
+  // #####################################
+
+  const timeline = #{
+    startDate: #{
+      name: "Project Start Date",
+      eventType: Fields.EventType.singleDate,
+      date: Types.isoDate.fromISO("2025-01-01"),
+    },
+    endDate: #{
+      name: "Project End Date",
+      eventType: Fields.EventType.singleDate,
+      date: Types.isoDate.fromISO("2025-12-31"),
+    },
+    otherDates: #{
+      evaluationPeriod: #{
+        name: "Evaluation Period",
+        eventType: Fields.EventType.dateRange,
+        startDate: Types.isoDate.fromISO("2025-07-01"),
+        endDate: Types.isoDate.fromISO("2025-08-31"),
+        description: "The period during which the evaluation will be conducted.",
+      },
+    },
+  };
+
+  // #####################################
+  // Contacts
+  // #####################################
+
+  const contacts = #{
+    primary: Examples.Person.examplePerson,
+    otherContacts: #{
+      principalInvestigator: #{
+        name: #{ prefix: "Dr.", firstName: "Alicia", lastName: "Williams" },
+        emails: #{ primary: "alicia.williams@example.com" },
+      },
+      authorizedRepresentative: #{
+        name: #{ firstName: "John", lastName: "Doe" },
+        emails: #{ primary: "john.doe@example.com" },
+      },
+    },
+  };
+
+  // #####################################
+  // Organizations
+  // #####################################
+
+  const organizations = #{
+    primary: Examples.Organization.exampleOrg,
+    otherOrgs: #{
+      fiscalSponsor: Examples.Organization.exampleOrg,
+      partner: Examples.Organization.exampleOrg,
+    },
+  };
+}

package/lib/core/responses/success.tsp

@@ -144,3 +144,19 @@ model Filtered<ItemsT, FilterT> extends Success {
     errors?: string[];
   };
 }
+
+// ############################################################################
+// 201 response
+// ############################################################################
+
+/** A 201 response with data
+ *
+ * @template T The schema for the value of the `"data"` property in this response
+ */
+model Created<T> extends Success {
+  // Inherit the 201 status code
+  ...Http.CreatedResponse;
+
+  /** Response data */
+  data: T;
+}

package/lib/core/routes/applications.tsp

@@ -0,0 +1,62 @@
+import "../responses/index.tsp";
+
+// Define the top-level namespace for CommonGrants routes
+namespace CommonGrants.Routes;
+
+// Expose the contents of the Http and Rest namespaces
+// these include the decorators @route, @get, etc.
+using TypeSpec.Http;
+
+/** A re-usable interface for an Applications router
+ *
+ * To implement this interface, we recommend declaring a namespace,
+ * instantiating the router using `alias` (instead of `extends`),
+ * and decorating the namespace with `@route` and `@tag` since they aren't
+ * inherited directly from the interface.
+ */
+interface Applications {
+  // ##############################
+  // Start an application
+  // ##############################
+
+  @summary("Start an application")
+  @doc("Start a draft application for a given competition")
+  @post
+  @route("/start")
+  startApplication(
+    /** The ID of the competition to start an application for */
+    competitionId: Types.uuid,
+
+    /** The ID of the organization to start an application for, if applying on behalf of an organization */
+    organizationId?: Types.uuid,
+
+    /** The name of the application */
+    name: string,
+  ): Responses.Created<Models.ApplicationBase> | Responses.Unauthorized;
+
+  // ###############################
+  // Get an application
+  // ###############################
+
+  @summary("View an application")
+  @doc("View an application for a given competition with draft form responses")
+  @get
+  @route("/{id}")
+  getApplication(
+    /** The ID of the application to get */
+    @path id: Types.uuid,
+  ): Responses.Ok<Models.ApplicationBase> | Responses.NotFound | Responses.Unauthorized;
+
+  // ###############################
+  // Submit an application
+  // ###############################
+
+  @summary("Submit an application")
+  @doc("Submit an application for a given competition")
+  @post
+  @route("/{id}/submit")
+  submitApplication(
+    /** The ID of the application to submit */
+    @path id: Types.uuid,
+  ): Http.NoContentResponse | Responses.NotFound | Responses.Unauthorized;
+}

package/lib/core/routes/competitions.tsp

@@ -0,0 +1,46 @@
+import "../responses/index.tsp";
+
+// Define the top-level namespace for CommonGrants routes
+namespace CommonGrants.Routes;
+
+// Expose the contents of the Http and Rest namespaces
+// these include the decorators @route, @get, etc.
+using TypeSpec.Http;
+
+/** A re-usable interface for a Competitions router
+ *
+ * To implement this interface, we recommend declaring a namespace,
+ * instantiating the router using `alias` (instead of `extends`),
+ * and decorating the namespace with `@route` and `@tag` since they aren't
+ * inherited directly from the interface.
+ */
+interface Competitions {
+  // ###############################
+  // View competition details
+  // ###############################
+
+  @summary("View competition details")
+  @doc("View additional details about a competition for a given opportunity. A competition is an application process for a funding opportunity, often with a distinct set of forms and key dates.")
+  @get
+  @route("/competitions/{id}")
+  read(
+    /** The ID of the competition to get */
+    @path id: Types.uuid,
+  ): Responses.Ok<Models.CompetitionBase> | Responses.NotFound;
+
+  // ###############################
+  // Apply to a competition
+  // ###############################
+
+  @summary("Apply to a competition")
+  @doc("Apply to a given competition with all of the required information")
+  @post
+  @route("/competitions/{id}/apply")
+  apply(
+    /** The ID of the competition to apply to */
+    @path id: Types.uuid,
+
+    /** The application to apply to the competition */
+    @body application: Models.ApplicationBase,
+  ): Responses.Created<Models.ApplicationBase> | Responses.NotFound | Responses.Unauthorized;
+}

package/lib/core/routes/form-responses.tsp

@@ -0,0 +1,52 @@
+import "../responses/index.tsp";
+
+// Define the top-level namespace for CommonGrants routes
+namespace CommonGrants.Routes;
+
+// Expose the contents of the Http and Rest namespaces
+// these include the decorators @route, @get, etc.
+using TypeSpec.Http;
+
+/** A re-usable interface for an Applications router
+ *
+ * To implement this interface, we recommend declaring a namespace,
+ * instantiating the router using `alias` (instead of `extends`),
+ * and decorating the namespace with `@route` and `@tag` since they aren't
+ * inherited directly from the interface.
+ */
+interface FormResponses {
+  // ###############################
+  // Update form response
+  // ###############################
+
+  @summary("Respond to a form")
+  @doc("Update the response to a given form on an application")
+  @put
+  @route("/{appId}/forms/{formId}")
+  setFormResponse(
+    /** The ID of the application to get */
+    @path appId: Types.uuid,
+
+    /** The ID of the form to update */
+    @path formId: Types.uuid,
+
+    /** The response to the form */
+    @body response: Record<unknown>,
+  ): Responses.Ok<Models.AppFormResponse>;
+
+  // ###############################
+  // Get form response
+  // ###############################
+
+  @summary("Get a form response")
+  @doc("Get the response to a given form on an application")
+  @get
+  @route("/{appId}/forms/{formId}")
+  getFormResponse(
+    /** The ID of the application to get */
+    @path appId: Types.uuid,
+
+    /** The ID of the form to get */
+    @path formId: Types.uuid,
+  ): Responses.Ok<Models.AppFormResponse>;
+}

package/lib/core/routes/index.tsp

@@ -3,6 +3,9 @@ import "@typespec/rest";
 
 // Import individual route files to provide a consistent interface
 import "./opportunities.tsp";
+import "./applications.tsp";
+import "./form-responses.tsp";
+import "./competitions.tsp";
 
 /** A series of routing interfaces for CommonGrants API endpoints
  *

package/lib/main.tsp

@@ -3,7 +3,19 @@
 // https://typespec.io/docs/extending-typespec/basics/#h-add-your-main-typespec-file
 import "../dist/src/index.js";
 
+// Import the core typespec files
 import "./core/index.tsp";
 import "./api.tsp";
 
+// Import the versioning package
+import "@typespec/versioning";
+
+using Versioning;
+
+@versioned(Versions)
 namespace CommonGrants;
+
+enum Versions {
+  v0_1: "0.1.0",
+  v0_2: "0.2.0",
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@common-grants/core",
-  "version": "0.1.1",
+  "version": "0.2.0-alpha.1",
   "description": "TypeSpec library for defining grant opportunity data models and APIs",
   "type": "module",
   "main": "dist/src/index.js",
@@ -55,7 +55,8 @@
     "@typespec/http": "^1.1.0",
     "@typespec/json-schema": "1.0.0",
     "@typespec/openapi3": "1.0.0",
-    "@typespec/rest": "0.70.0"
+    "@typespec/rest": "0.70.0",
+    "@typespec/versioning": "^0.70.0"
   },
   "devDependencies": {
     "@types/node": "^20.10.6",