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

package/README.md

@@ -34,12 +34,14 @@ The Opportunity model is templated to support custom fields. First define your c
 // models.tsp
 
 import "@common-grants/core"; // Import the base specification library
+import "@typespec/versioning";
 
 // Allows us to use models and fields defined in the core library without
 // prefixing each item with `CommonGrants.Models` or `CommonGrants.Fields`
 using CommonGrants.Models;
 using CommonGrants.Fields;
 
+@Versioning.useDependency(CommonGrants.Versions.v0_2) // Specify the version of the core library to use
 namespace CustomAPI.CustomModels;
 
 // Define a custom field
@@ -77,6 +79,7 @@ using TypeSpec.Http;
 
 @tag("Search")
 @route("/common-grants/opportunities")
+@Versioning.useDependency(CommonGrants.Versions.v0_2)
 namespace CustomAPI.CustomRoutes {
   alias OpportunitiesRouter = Opportunities;
 
@@ -117,10 +120,16 @@ Or specify the emitter in `tspconfig.yaml`:
 
 ```yaml
 # tspconfig.yaml
-emitters:
+emit:
   - "@typespec/openapi3"
 ```
 
+And run the following command:
+
+```bash
+npx tsp compile main.tsp
+```
+
 Both strategies will generate an OpenAPI specification in the `tsp-output/` directory.
 
 ### Further reading

package/lib/api.tsp

@@ -30,16 +30,22 @@ using Versioning;
     description: "Endpoints that MUST be implemented by all CommonGrants APIs",
   }
 )
+@tagMetadata("Forms", #{ description: "Endpoints related to forms" })
 @tagMetadata(
   "Applications",
+  #{ description: "Endpoints related to applications for a given competition" }
+)
+@tagMetadata(
+  "Competitions",
   #{
-    description: "Endpoints related to applications for funding opportunities",
+    description: "Endpoints related to competitions, which are distinct application processes for the same funding opportunity",
   }
 )
 @tagMetadata(
   "Opportunities",
   #{ description: "Endpoints related to funding opportunities" }
 )
+@route("/common-grants") // Prefixes all routes with `/common-grants/`
 namespace CommonGrants.API;
 
 // #########################################################
@@ -47,7 +53,7 @@ namespace CommonGrants.API;
 // #########################################################
 
 @tag("Opportunities")
-@route("/common-grants/opportunities")
+@route("/opportunities")
 namespace Opportunities {
   alias Router = Routes.Opportunities;
 
@@ -61,63 +67,70 @@ namespace Opportunities {
   op search is Router.search;
 }
 
+// #########################################################
+// Competitions
+// #########################################################
+
+@tag("Competitions")
+@tag("experimental")
+@route("/competitions")
+namespace Competitions {
+  alias Router = Routes.Competitions;
+
+  op read is Router.read;
+}
+
 // #########################################################
 // 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;
-  }
+@route("/applications")
+namespace Applications {
+  alias ApplicationRouter = Routes.Applications;
+  alias FormResponseRouter = Routes.FormResponses;
 
-  // #########################################################
-  // Multi-step workflow
-  // #########################################################
+  // ################################
+  // Start an application workflow
+  // ################################
 
-  @route("/applications")
-  namespace MultiStepWorkflow {
-    alias ApplicationRouter = Routes.Applications;
-    alias FormResponseRouter = Routes.FormResponses;
+  @added(Versions.v0_2)
+  op startApplication is ApplicationRouter.startApplication;
 
-    // ################################
-    // Start an application workflow
-    // ################################
+  @added(Versions.v0_2)
+  op getApplication is ApplicationRouter.getApplication;
 
-    @added(Versions.v0_2)
-    op startApplication is ApplicationRouter.startApplication;
+  // ################################
+  // Update form responses
+  // ################################
 
-    @added(Versions.v0_2)
-    op getApplication is ApplicationRouter.getApplication;
+  @added(Versions.v0_2)
+  op setFormResponse is FormResponseRouter.setFormResponse;
 
-    // ################################
-    // Update form responses
-    // ################################
+  @added(Versions.v0_2)
+  op getFormResponse is FormResponseRouter.getFormResponse;
 
-    @added(Versions.v0_2)
-    op setFormResponse is FormResponseRouter.setFormResponse;
+  // ################################
+  // Submit an application after completing all forms
+  // ################################
 
-    @added(Versions.v0_2)
-    op getFormResponse is FormResponseRouter.getFormResponse;
+  @added(Versions.v0_2)
+  op submitApplication is ApplicationRouter.submitApplication;
+}
 
-    // ################################
-    // Submit an application after completing all forms
-    // ################################
+// #########################################################
+// Forms
+// #########################################################
 
-    @added(Versions.v0_2)
-    op submitApplication is ApplicationRouter.submitApplication;
-  }
+@tag("Forms")
+@route("/forms")
+namespace Forms {
+  alias Router = Routes.Forms;
+
+  @tag("optional")
+  op list is Router.list;
+
+  @tag("optional")
+  op read is Router.read;
 }

package/lib/core/models/applicant-type.tsp

@@ -0,0 +1,96 @@
+namespace CommonGrants.Models;
+
+// #########################################################
+// ApplicantType
+// #########################################################
+
+/** The type of applicant eligible to apply for funding */
+@example(Examples.ApplicantType.organization)
+@example(Examples.ApplicantType.individual)
+model ApplicantType {
+  /** The type of applicant */
+  value: ApplicantTypeOptions;
+
+  /** The custom value for the applicant type */
+  customValue?: string;
+
+  /** The description of the applicant type */
+  description?: string;
+}
+
+// #########################################################
+// ApplicantTypeOptions
+// #########################################################
+
+/** The set of possible applicant types */
+enum ApplicantTypeOptions {
+  /** The applicant is an individual */
+  individual,
+
+  /** Any type of organization */
+  organization,
+
+  /** State government */
+  government_state,
+
+  /** County government */
+  government_county,
+
+  /** City or township government */
+  government_municipal,
+
+  /** Special district government */
+  government_special_district,
+
+  /** Federally recognized Native American tribal government */
+  government_tribal,
+
+  /** Native American tribal organization that is not federally recognized */
+  organization_tribal_other,
+
+  /** Independent school district */
+  school_district_independent,
+
+  /** Public or state institution of higher education */
+  higher_education_public,
+
+  /** Private institution of higher education */
+  higher_education_private,
+
+  /** Non-profit organization with 501(c)(3) status */
+  non_profit_with_501c3,
+
+  /** Non-profit organization without 501(c)(3) status */
+  nonprofit_without_501c3,
+
+  /** For-profit small business */
+  for_profit_small_business,
+
+  /** For-profit organization that is not a small business */
+  for_profit_not_small_business,
+
+  /** Anyone can apply (unrestricted) */
+  unrestricted,
+
+  /** Custom applicant type */
+  custom,
+}
+
+// #########################################################
+// ApplicantTypeExamples
+// #########################################################
+
+/** Examples of applicant types */
+namespace Examples.ApplicantType {
+  /** The applicant is an individual */
+  const individual = #{
+    value: ApplicantTypeOptions.individual,
+    description: "An individual applicant",
+  };
+
+  /** Any type of organization */
+  const organization = #{
+    value: ApplicantTypeOptions.organization,
+    description: "Any type of organization",
+  };
+}

package/lib/core/models/application.tsp

@@ -1,5 +1,7 @@
 namespace CommonGrants.Models;
 
+/** The base model for an application to a competition for a funding opportunity */
+@example(Examples.Application.applicationBase)
 model ApplicationBase {
   /** The unique identifier for the application */
   id: Types.uuid;
@@ -19,6 +21,9 @@ model ApplicationBase {
   /** The date and time the application was submitted */
   submittedAt?: utcDateTime | null;
 
+  /** The validation errors for the application and form responses */
+  validationErrors?: Array<unknown>;
+
   /** The custom fields about the application */
   customFields?: Record<Fields.CustomField>;
 
@@ -30,16 +35,16 @@ model ApplicationBase {
 // AppStatus
 // #########################################################
 
-/** The status of the application. */
+/** The status of the application */
 @example(Examples.Application.submittedStatus)
 model AppStatus {
-  /** The status of the application. */
+  /** The status of the application, from a predefined set of options */
   value: AppStatusOptions;
 
-  /** A custom value for the status. */
+  /** A custom value for the status */
   customValue?: string;
 
-  /** A description of the status. */
+  /** A human-readable description of the status */
   description?: string;
 }
 
@@ -47,21 +52,18 @@ model AppStatus {
 // AppStatusOptions
 // #########################################################
 
-/** The default set of values accepted for application status. */
+/** The default set of values accepted for application status:
+ * - `inProgress`: The application is in progress
+ * - `submitted`: The application has been submitted and is being reviewed
+ * - `accepted`: The application has been accepted
+ * - `rejected`: The application has been rejected
+ * - `custom`: A custom status
+ */
 enum AppStatusOptions {
-  /** The application is a draft */
-  draft,
-
-  /** The application has been submitted */
+  inProgress,
   submitted,
-
-  /** The application has been accepted */
   accepted,
-
-  /** The application has been rejected */
   rejected,
-
-  /** The application has a custom status */
   custom,
 }
 
@@ -69,9 +71,14 @@ enum AppStatusOptions {
 // ApplicationFormResponse
 // #########################################################
 
-model AppFormResponse extends FormResponseBase {
+/** The model for a form response included in an application */
+@example(Examples.Application.formResponse)
+model AppFormResponse {
   /** The unique identifier for the application */
   applicationId: Types.uuid;
+
+  /** Includes all the fields from the FormResponseBase model */
+  ...FormResponseBase;
 }
 
 // #########################################################
@@ -84,9 +91,30 @@ namespace Examples.Application {
     description: "The application has been submitted.",
   };
 
+  const inProgressStatus = #{
+    value: AppStatusOptions.inProgress,
+    description: "The application is in progress.",
+  };
+
   const customStatus = #{
     value: AppStatusOptions.custom,
-    customValue: "draft",
-    description: "Application is started but not yet submitted.",
+    customValue: "cancelled",
+    description: "Application was cancelled before it was submitted.",
+  };
+
+  const formResponse = #{
+    applicationId: "123e4567-e89b-12d3-a456-426614174000",
+    ...Examples.FormResponse.formResponse,
+  };
+
+  const applicationBase = #{
+    id: "123e4567-e89b-12d3-a456-426614174000",
+    name: "My Application",
+    competitionId: "123e4567-e89b-12d3-a456-426614174000",
+    formResponses: #{ formA: formResponse },
+    status: inProgressStatus,
+    submittedAt: null,
+    createdAt: utcDateTime.fromISO("2021-01-01T00:00:00Z"),
+    lastModifiedAt: utcDateTime.fromISO("2021-01-01T00:00:00Z"),
   };
 }

package/lib/core/models/competition.tsp

@@ -21,17 +21,20 @@ model CompetitionBase {
   description?: string;
 
   /** The instructions for the competition */
-  instructions?: string | Fields.File;
+  instructions?: string | Fields.File[];
 
   /** The status of the competition */
   status: CompetitionStatus;
 
   /** The key dates in the competition timeline */
-  keyDates: CompetitionTimeline;
+  keyDates?: CompetitionTimeline;
 
   /** The forms for the competition */
   forms: CompetitionForms;
 
+  /** Accepted applicant types for the competition */
+  acceptedApplicantTypes?: ApplicantType[];
+
   /** The custom fields for the competition */
   customFields?: Record<Fields.CustomField>;
 
@@ -46,8 +49,13 @@ model CompetitionBase {
 /** The status of the competition */
 @example(Examples.Competition.status)
 model CompetitionStatus {
+  /** The status of the competition, from a predefined set of options */
   value: CompetitionStatusOptions;
+
+  /** A custom value for the status */
   customValue?: string;
+
+  /** A human-readable description of the status */
   description?: string;
 }
 
@@ -55,14 +63,14 @@ model CompetitionStatus {
 // CompetitionStatusOptions
 // #########################################################
 
+/** The set of values accepted for competition status
+ * - `open`: The competition is open for applications
+ * - `closed`: The competition is no longer accepting applications
+ * - `custom`: A custom status
+ */
 enum CompetitionStatusOptions {
-  /** The competition is open for applications */
   open,
-
-  /** The competition is closed for applications */
   closed,
-
-  /** The competition is in a custom status */
   custom,
 }
 
@@ -77,7 +85,7 @@ model CompetitionForms {
   forms: Record<Models.Form>;
 
   /** The validation rules for the competition forms */
-  validation: Record<unknown>;
+  validation?: Record<unknown>;
 }
 
 // #########################################################
@@ -87,10 +95,10 @@ model CompetitionForms {
 @example(Examples.Competition.keyDates)
 model CompetitionTimeline {
   /** The start date of the competition */
-  openDate: Fields.Event;
+  openDate?: Fields.Event;
 
   /** The end date of the competition */
-  closeDate: Fields.Event;
+  closeDate?: Fields.Event;
 
   /** The date the competition was created */
   otherDates?: Record<Fields.Event>;

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

@@ -1,12 +1,13 @@
 namespace CommonGrants.Models;
 
 /** The base model for a form response */
+@example(Examples.FormResponse.formResponse)
 model FormResponseBase {
   /** The unique identifier for the form response */
   id: Types.uuid;
 
   /** The form being responded to */
-  form: Form;
+  formId: Types.uuid;
 
   /** The response to the form */
   response: Record<unknown>;
@@ -15,7 +16,10 @@ model FormResponseBase {
   status: FormResponseStatus;
 
   /** The validation errors for the form response */
-  validationErrors: Array<unknown>;
+  validationErrors?: Array<unknown>;
+
+  /** Custom attributes about the form response */
+  customFields?: Record<Fields.CustomField>;
 
   /** The system metadata for the form response */
   ...Fields.SystemMetadata;
@@ -28,13 +32,13 @@ model FormResponseBase {
 /** The status of the form response */
 @example(Examples.FormResponse.inProgressStatus)
 model FormResponseStatus {
-  /** The status of the form response */
+  /** The status of the form response, from a predefined set of options */
   value: FormResponseStatusOptions;
 
   /** A custom value for the status */
   customValue?: string;
 
-  /** A description of the status */
+  /** A human-readable description of the status */
   description?: string;
 }
 
@@ -42,15 +46,15 @@ model FormResponseStatus {
 // FormResponseStatusOptions
 // #########################################################
 
-/** The options for the status of the form response */
+/** The set of values accepted for form response status:
+ * - `notStarted`: The form response has not been started
+ * - `inProgress`: The form response is in progress
+ * - `complete`: The form response is complete, meaning all required fields have been filled out and there are no validation errors
+ * - `custom`: A custom status
+ */
 enum FormResponseStatusOptions {
-  /** The form response has not been started */
   notStarted,
-
-  /** The form response is in progress */
   inProgress,
-
-  /** The form response is submitted */
   complete,
 }
 
@@ -68,4 +72,28 @@ namespace Examples.FormResponse {
     value: FormResponseStatusOptions.complete,
     description: "The form response is complete",
   };
+
+  const formResponse = #{
+    id: "123e4567-e89b-12d3-a456-426614174000",
+    formId: "123e4567-e89b-12d3-a456-426614174000",
+    response: #{
+      firstName: "John",
+      lastName: "Doe",
+      email: "john.doe@example.com",
+      phone: "123-456-7890",
+      address: #{
+        street: "123 Main St",
+        city: "Anytown",
+        state: "CA",
+        zip: "12345",
+        country: null,
+      },
+    },
+    status: inProgressStatus,
+    validationErrors: #[
+      #{ field: "address.country", message: "Country is required" }
+    ],
+    createdAt: utcDateTime.fromISO("2021-01-01T00:00:00Z"),
+    lastModifiedAt: utcDateTime.fromISO("2021-01-01T00:00:00Z"),
+  };
 }

package/lib/core/models/form.tsp

@@ -19,7 +19,7 @@ model Form {
   description?: string;
 
   /** The form's instructions. */
-  instructions?: string | Fields.File;
+  instructions?: string | Fields.File[];
 
   /** The form's JSON schema used to render the form and validate responses. */
   jsonSchema?: FormJsonSchema;

package/lib/core/models/index.tsp

@@ -11,6 +11,7 @@ import "./competition.tsp";
 import "./form.tsp";
 import "./form-response.tsp";
 import "./mapping.tsp";
+import "./applicant-type.tsp";
 
 using TypeSpec.JsonSchema;
 

package/lib/core/models/mapping.tsp

@@ -4,7 +4,7 @@ namespace CommonGrants.Models;
 // Mapping
 // #########################################################
 
-/** A mapping schema for translating data from one schema to another.
+/** A mapping format for translating data from one schema to another.
  *
  * Example:
  *
@@ -16,12 +16,12 @@ namespace CommonGrants.Models;
  *   "opportunity": {
  *     "status": {
  *       "switch": {
- *         "field": "opportunity_status",
+ *         "field": "summary.opportunity_status",
  *         "case": { "active": "open", "inactive": "closed" },
  *         "default": "custom",
  *       },
  *     },
- *     "amount": { "field": "opportunity_amount" },
+ *     "amount": { "field": "summary.opportunity_amount" },
  *   }
  * }
  * ```
@@ -31,8 +31,10 @@ namespace CommonGrants.Models;
  * ```json
  * {
  *   "id": "123",
- *   "opportunity_status": "active",
- *   "opportunity_amount": 100,
+ *   "summary": {
+ *     "opportunity_status": "active",
+ *     "opportunity_amount": 100,
+ *   },
  * }
  * ```
  *
@@ -43,6 +45,7 @@ namespace CommonGrants.Models;
  *   "id": "123",
  *   "opportunity": { "status": "open", "amount": 100 },
  * }
+ * ```
  */
 @example(Examples.Mapping.flatRenaming)
 @example(Examples.Mapping.nestedRenaming)
@@ -50,7 +53,7 @@ namespace CommonGrants.Models;
 @example(Examples.Mapping.nestedSwitch)
 @example(Examples.Mapping.withLiteralValues)
 model MappingSchema {
-  ...Record<MappingFunction | unknown>;
+  ...Record<MappingFunction | MappingSchema>;
 }
 
 // #########################################################
@@ -58,6 +61,9 @@ model MappingSchema {
 // #########################################################
 
 /** The set of supported mapping functions. */
+@example(Examples.Mapping.constId)
+@example(Examples.Mapping.amountField)
+@example(Examples.Mapping.statusSwitch)
 union MappingFunction {
   `const`: MappingConstantFunction,
   field: MappingFieldFunction,
@@ -65,10 +71,11 @@ union MappingFunction {
 }
 
 // #########################################################
-// MappingLiteralFunction
+// MappingConstantFunction
 // #########################################################
 
 /** Returns a constant value. */
+@example(Examples.Mapping.constId)
 model MappingConstantFunction {
   `const`: unknown;
 }
@@ -78,6 +85,7 @@ model MappingConstantFunction {
 // #########################################################
 
 /** Returns the value of a field in the source data. */
+@example(Examples.Mapping.amountField)
 model MappingFieldFunction {
   field: string;
 }
@@ -87,15 +95,18 @@ model MappingFieldFunction {
 // #########################################################
 
 /** Returns a new value based on the value of a field in the source data using a switch statement. */
+@example(Examples.Mapping.statusSwitch)
 model MappingSwitchFunction {
-  /** The field in the source data to switch on. */
-  field: string;
+  switch: {
+    /** The field in the source data to switch on. */
+    field: string;
 
-  /** An object mapping source field values to desired output values. */
-  case: Record<unknown>;
+    /** 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;
+    /** The default value to output if no case matches the source field value. */
+    default?: unknown;
+  };
 }
 
 // #########################################################
@@ -103,60 +114,39 @@ model MappingSwitchFunction {
 // #########################################################
 
 namespace Examples.Mapping {
+  const constId = #{ `const`: "123" };
+  const amountField = #{ field: "summary.opportunity_amount" };
+  const statusField = #{ field: "summary.opportunity_status" };
+  const statusSwitch = #{
+    switch: #{
+      field: "summary.opportunity_status",
+      case: #{ active: "open", inactive: "closed" },
+      default: "custom",
+    },
+  };
+
   const flatRenaming = #{
-    opportunityStatus: #{ field: "opportunity_status" },
-    opportunityAmount: #{ field: "opportunity_amount" },
+    id: constId,
+    opportunityStatus: statusField,
+    opportunityAmount: amountField,
   };
 
   const nestedRenaming = #{
-    id: #{ field: "opportunity_id" },
-    opportunity: #{
-      status: #{ field: "opportunity_status" },
-      amount: #{ field: "opportunity_amount" },
-    },
+    id: constId,
+    opportunity: #{ status: statusField, amount: amountField },
   };
 
   const simpleSwitch = #{
-    opportunityAmount: #{ field: "opportunity_amount" },
-    opportunityStatus: #{
-      switch: #{
-        field: "opportunity_status",
-        case: #{ active: "open", inactive: "closed" },
-        default: "custom",
-      },
-    },
+    opportunityAmount: amountField,
+    opportunityStatus: statusSwitch,
   };
 
   const nestedSwitch = #{
-    opportunity: #{
-      status: #{
-        switch: #{
-          field: "opportunity_status",
-          case: #{ active: "open", inactive: "closed" },
-          default: "custom",
-        },
-        amount: #{ field: "opportunity_amount" },
-      },
-    },
+    opportunity: #{ status: statusSwitch, amount: amountField },
   };
 
   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" },
+    id: constId,
+    opportunity: #{ status: statusSwitch, amount: amountField },
   };
 }

package/lib/core/models/opportunity/base.tsp

@@ -62,6 +62,9 @@ model OpportunityBase {
   /** Key dates for the opportunity, such as when the application opens and closes */
   keyDates?: OppTimeline;
 
+  /** The type of applicant for the opportunity */
+  acceptedApplicantTypes?: ApplicantType[];
+
   /** URL for the original source of the opportunity */
   source?: url;
 
@@ -71,3 +74,13 @@ model OpportunityBase {
   // Spreads the fields from the Metadata model into the Opportunity model
   ...SystemMetadata;
 }
+
+// ########################################
+// Opportunity details
+// ########################################
+
+/** A funding opportunity with additional details, like available competitions. */
+model OpportunityDetails extends OpportunityBase {
+  /** The competitions associated with the opportunity */
+  competitions?: CompetitionBase[];
+}

package/lib/core/models/opportunity/status.tsp

@@ -4,7 +4,12 @@ namespace CommonGrants.Models;
 // Opportunity status options
 // ########################################
 
-/** The set of values accepted for opportunity status */
+/** The set of values accepted for opportunity status:
+ * - `forecasted`: The opportunity is forecasted and not yet open for applications
+ * - `open`: The opportunity is open for applications
+ * - `closed`: The opportunity is no longer accepting applications
+ * - `custom`: A custom status
+ */
 enum OppStatusOptions {
   forecasted,
   open,
@@ -20,10 +25,10 @@ enum OppStatusOptions {
 @example(Examples.OppStatus.custom)
 @example(Examples.OppStatus.default)
 model OppStatus {
-  /** The status value, from a predefined set of options */
+  /** The status of the opportunity, from a predefined set of options */
   value: OppStatusOptions;
 
-  /** A custom status value */
+  /** A custom value for the status */
   customValue?: string;
 
   /** A human-readable description of the status */

package/lib/core/responses/error.tsp

@@ -28,3 +28,14 @@ model Error {
 
 alias Unauthorized = Error & Http.UnauthorizedResponse;
 alias NotFound = Error & Http.NotFoundResponse;
+
+@example(#{
+  status: 400,
+  message: "Application submission failed due to validation errors",
+  errors: #[#{ field: "formA.name", message: "Name is required" }],
+})
+@doc("A failure to submit an application due to validation errors")
+model ApplicationSubmissionError extends Error {
+  @example(400)
+  status: 400;
+}

package/lib/core/routes/applications.tsp

@@ -20,7 +20,7 @@ interface Applications {
   // ##############################
 
   @summary("Start an application")
-  @doc("Start a draft application for a given competition")
+  @doc("Start a new application for a given competition.")
   @post
   @route("/start")
   startApplication(
@@ -39,12 +39,12 @@ interface Applications {
   // ###############################
 
   @summary("View an application")
-  @doc("View an application for a given competition with draft form responses")
+  @doc("View an application for a given competition, along with its form responses and validation errors.")
   @get
-  @route("/{id}")
+  @route("/{appId}")
   getApplication(
     /** The ID of the application to get */
-    @path id: Types.uuid,
+    @path appId: Types.uuid,
   ): Responses.Ok<Models.ApplicationBase> | Responses.NotFound | Responses.Unauthorized;
 
   // ###############################
@@ -52,11 +52,15 @@ interface Applications {
   // ###############################
 
   @summary("Submit an application")
-  @doc("Submit an application for a given competition")
-  @post
-  @route("/{id}/submit")
+  @doc("Submit an application to a competition. Applications that have validation errors will be blocked from submitting until the errors are fixed.")
+  @put
+  @route("/{appId}/submit")
   submitApplication(
     /** The ID of the application to submit */
-    @path id: Types.uuid,
-  ): Http.NoContentResponse | Responses.NotFound | Responses.Unauthorized;
+    @path appId: Types.uuid,
+  ):
+    | Responses.Ok<unknown>
+    | Responses.ApplicationSubmissionError
+    | Responses.NotFound
+    | Responses.Unauthorized;
 }

package/lib/core/routes/competitions.tsp

@@ -19,13 +19,17 @@ interface Competitions {
   // View competition details
   // ###############################
 
+  /** View details about a competition for a given funding opportunity.
+   *
+   * Each competition may have a distinct set of forms, be limited to a
+   * certain types of applicants, or have a different application period.
+   */
   @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}")
+  @route("/{compId}")
   read(
-    /** The ID of the competition to get */
-    @path id: Types.uuid,
+    /** The ID of the competition to view */
+    @path compId: Types.uuid,
   ): Responses.Ok<Models.CompetitionBase> | Responses.NotFound;
 
   // ###############################
@@ -33,12 +37,12 @@ interface Competitions {
   // ###############################
 
   @summary("Apply to a competition")
-  @doc("Apply to a given competition with all of the required information")
+  @doc("Apply to a given competition with all of the required information.")
   @post
-  @route("/competitions/{id}/apply")
+  @route("/{compId}/apply")
   apply(
     /** The ID of the competition to apply to */
-    @path id: Types.uuid,
+    @path compId: Types.uuid,
 
     /** The application to apply to the competition */
     @body application: Models.ApplicationBase,

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

@@ -20,14 +20,14 @@ interface FormResponses {
   // ###############################
 
   @summary("Respond to a form")
-  @doc("Update the response to a given form on an application")
+  @doc("Set or update the response to a given form in an application.")
   @put
   @route("/{appId}/forms/{formId}")
   setFormResponse(
-    /** The ID of the application to get */
+    /** The ID of the application to whose form response is being updated */
     @path appId: Types.uuid,
 
-    /** The ID of the form to update */
+    /** The ID of the form whose response is being updated */
     @path formId: Types.uuid,
 
     /** The response to the form */
@@ -39,14 +39,14 @@ interface FormResponses {
   // ###############################
 
   @summary("Get a form response")
-  @doc("Get the response to a given form on an application")
+  @doc("Get the response to a given form in an application.")
   @get
   @route("/{appId}/forms/{formId}")
   getFormResponse(
-    /** The ID of the application to get */
+    /** The ID of the application to whose form response is being retrieved */
     @path appId: Types.uuid,
 
-    /** The ID of the form to get */
+    /** The ID of the form whose response is being retrieved */
     @path formId: Types.uuid,
   ): Responses.Ok<Models.AppFormResponse>;
 }

package/lib/core/routes/forms.tsp

@@ -0,0 +1,38 @@
+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 Forms {
+  // ###############################
+  // Update form response
+  // ###############################
+
+  @summary("List forms")
+  @doc("Get a paginated list of forms, sorted by `lastModifiedAt` with most recent first.")
+  @get
+  list(...Pagination.PaginatedQueryParams): Responses.Paginated<Models.Form>;
+
+  // ###############################
+  // View form details
+  // ###############################
+
+  @summary("View form details")
+  @doc("View details about a given form.")
+  @get
+  read(
+    /** The ID of the form to view */
+    @path formId: Types.uuid,
+  ): Responses.Ok<Models.Form>;
+}

package/lib/core/routes/index.tsp

@@ -5,6 +5,7 @@ import "@typespec/rest";
 import "./opportunities.tsp";
 import "./applications.tsp";
 import "./form-responses.tsp";
+import "./forms.tsp";
 import "./competitions.tsp";
 
 /** A series of routing interfaces for CommonGrants API endpoints

package/lib/core/routes/opportunities.tsp

@@ -8,6 +8,7 @@ namespace CommonGrants.Routes;
 // Expose the contents of the Http and Rest namespaces
 // these include the decorators @route, @get, etc.
 using TypeSpec.Http;
+using TypeSpec.Versioning;
 
 /** A re-usable interface for an Opportunities router
  *
@@ -52,7 +53,7 @@ interface Opportunities {
   ): Responses.Paginated<T>;
 
   // ##############################
-  // View an opportunity
+  // View an opportunity (v0.1.0)
   // ##############################
 
   /** `GET /opportunities/<id>` View opportunity details
@@ -60,12 +61,19 @@ interface Opportunities {
    * @template T Type of the response model.
    * Must be an extension of Schemas.OpportunityBase. Default is Schemas.OpportunityBase.
    */
-  @summary("View opportunity")
-  @doc("View additional details about an opportunity")
+  @summary("View opportunity details")
+  @doc("View details about an opportunity.")
   @get
-  read<T extends Models.OpportunityBase = Models.OpportunityBase>(
+  read<T extends Models.OpportunityBase = Models.OpportunityDetails>(
     /** The ID of the opportunity to view */
-    @path id: Types.uuid,
+    @path
+    @removed(Versions.v0_2)
+    id: Types.uuid,
+
+    /** The ID of the opportunity to view */
+    @path
+    @added(Versions.v0_2)
+    oppId: Types.uuid,
   ): Responses.Ok<T> | Responses.NotFound;
 
   // ###############################
@@ -78,7 +86,7 @@ interface Opportunities {
    * Must be an extension of Schemas.OpportunityBase. Default is Schemas.OpportunityBase.
    */
   @summary("Search opportunities")
-  @doc("Search for opportunities based on the provided filters")
+  @doc("Search for opportunities based on the provided filters.")
   @post
   @route("/search")
   search<T extends Models.OpportunityBase = Models.OpportunityBase>(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@common-grants/core",
-  "version": "0.2.0-alpha.1",
+  "version": "0.2.0",
   "description": "TypeSpec library for defining grant opportunity data models and APIs",
   "type": "module",
   "main": "dist/src/index.js",