@common-grants/core 0.1.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

@@ -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,14 +30,30 @@ using TypeSpec.OpenAPI;
     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 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;
 
+// #########################################################
+// Opportunities
+// #########################################################
+
 @tag("Opportunities")
-@route("/common-grants/opportunities")
+@route("/opportunities")
 namespace Opportunities {
   alias Router = Routes.Opportunities;
 
@@ -42,3 +66,71 @@ namespace Opportunities {
   @tag("optional")
   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("/applications")
+namespace Applications {
+  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;
+}
+
+// #########################################################
+// Forms
+// #########################################################
+
+@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/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/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,49 +1,50 @@
-import "../index.tsp";
-
 namespace CommonGrants.Models;
 
-/** The base model for an application. */
-@example(Examples.Application.exampleApplication)
+/** The base model for an application to a competition for a funding opportunity */
+@example(Examples.Application.applicationBase)
 model ApplicationBase {
-  /** The application's unique identifier. */
+  /** The unique identifier for the application */
   id: Types.uuid;
 
-  /** The application's status. */
-  status?: AppStatus;
+  /** The name of the application */
+  name: string;
 
-  /** The application's date of submission. */
-  dateSubmitted?: Types.isoDate;
+  /** The unique identifier for the competition */
+  competitionId: Types.uuid;
 
-  /** The organization that is applying for the grant. */
-  organization?: OrganizationBase;
+  /** The form responses for the application */
+  formResponses: Record<AppFormResponse>;
 
-  /** The person who is applying for the grant. */
-  pointOfContact?: PersonBase;
+  /** The status of the application */
+  status: AppStatus;
 
-  /** The application's proposal for funding. */
-  proposal?: AppProposal;
+  /** The date and time the application was submitted */
+  submittedAt?: utcDateTime | null;
 
-  /** The opportunity being applied to. */
-  opportunity?: AppOpportunity;
+  /** The validation errors for the application and form responses */
+  validationErrors?: Array<unknown>;
 
-  /** The application's custom fields. */
+  /** The custom fields about the application */
   customFields?: Record<Fields.CustomField>;
+
+  /** The system metadata for the application */
+  ...Fields.SystemMetadata;
 }
 
 // #########################################################
 // 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;
 }
 
@@ -51,54 +52,33 @@ 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 {
+  inProgress,
   submitted,
-  approved,
+  accepted,
   rejected,
   custom,
 }
 
 // #########################################################
-// 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 start date of the period for which the funding is requested. */
-  periodStartDate?: Types.isoDate;
-
-  /** The end date of the period for which the funding is requested. */
-  periodEndDate?: Types.isoDate;
-
-  /** The project's custom fields. */
-  customFields?: Record<Fields.CustomField>;
-}
-
-// #########################################################
-// 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 model for a form response included in an application */
+@example(Examples.Application.formResponse)
+model AppFormResponse {
+  /** The unique identifier for the application */
+  applicationId: Types.uuid;
 
-  /** The opportunity's custom fields. */
-  customFields?: Record<Fields.CustomField>;
+  /** Includes all the fields from the FormResponseBase model */
+  ...FormResponseBase;
 }
 
 // #########################################################
@@ -106,37 +86,35 @@ 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 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 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 formResponse = #{
+    applicationId: "123e4567-e89b-12d3-a456-426614174000",
+    ...Examples.FormResponse.formResponse,
   };
 
-  const exampleOpportunity = #{
-    id: "083b4567-e89d-42c8-a439-6c1234567890",
-    title: "Example Opportunity",
+  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

@@ -0,0 +1,156 @@
+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;
+
+  /** Accepted applicant types for the competition */
+  acceptedApplicantTypes?: ApplicantType[];
+
+  /** 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 {
+  /** 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;
+}
+
+// #########################################################
+// 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 {
+  open,
+  closed,
+  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"] },
+  };
+}