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

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;
 
@@ -55,69 +61,82 @@ namespace Opportunities {
   op list is Router.list;
 
   @tag("required")
+  @returnTypeChangedFrom(
+    CommonGrants.Versions.v0_2,
+    Responses.Ok<Models.OpportunityBase> | Responses.NotFound
+  )
   op read is Router.read;
 
   @tag("optional")
   op search is Router.search;
 }
 
+// #########################################################
+// Competitions
+// #########################################################
+
+@tag("Competitions")
+@tag("experimental")
+@route("/competitions")
+namespace Competitions {
+  alias Router = Routes.Competitions;
+
+  @added(Versions.v0_2)
+  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")
+@tag("experimental")
+@route("/forms")
+namespace Forms {
+  alias Router = Routes.Forms;
+
+  @added(Versions.v0_2)
+  op list is Router.list;
+
+  @added(Versions.v0_2)
+  op read is Router.read;
 }

package/lib/core/fields/address.tsp

@@ -2,6 +2,7 @@ namespace CommonGrants.Fields;
 
 /** A mailing address. */
 @example(Examples.Address.apartment)
+@Versioning.added(CommonGrants.Versions.v0_2)
 model Address {
   /** The primary street address line. */
   street1: string;
@@ -34,6 +35,7 @@ model Address {
 /** A collection of addresses. */
 @example(Examples.Address.personalCollection)
 @example(Examples.Address.orgCollection)
+@Versioning.added(CommonGrants.Versions.v0_2)
 model AddressCollection {
   /** The primary address for a person or organization. */
   primary: Address;

package/lib/core/fields/email.tsp

@@ -7,6 +7,7 @@ alias Email = Types.email; // Exposes Email from CommonGrants.Fields
 
 /** A collection of email addresses. */
 @example(Examples.Email.personalCollection)
+@Versioning.added(CommonGrants.Versions.v0_2)
 model EmailCollection {
   /** The primary email address for a person or organization. */
   primary: Types.email;

package/lib/core/fields/file.tsp

@@ -3,6 +3,7 @@ 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" })
+@Versioning.added(CommonGrants.Versions.v0_2)
 model File {
   /** The file's download URL. */
   downloadUrl: url;

package/lib/core/fields/name.tsp

@@ -2,6 +2,7 @@ namespace CommonGrants.Fields;
 
 /** A person's name. */
 @example(Examples.Name.janeDoe)
+@Versioning.added(CommonGrants.Versions.v0_2)
 model Name {
   /** Honorific prefix (e.g., Mr., Mrs., Dr., Prof.). */
   prefix?: string;

package/lib/core/fields/pcs.tsp

@@ -13,6 +13,7 @@ namespace CommonGrants.Fields;
  * See https://taxonomy.candid.org/ for more information.
  */
 @example(Examples.PCS.orgTypeTerm)
+@Versioning.added(CommonGrants.Versions.v0_2)
 model PCSTerm {
   /** The plain language PCS term. */
   term: string;
@@ -34,6 +35,7 @@ model PCSTerm {
 // #########################################################
 
 /** The class to which the PCS term belongs. */
+@Versioning.added(CommonGrants.Versions.v0_2)
 enum PCSClass {
   orgTypes: "Organization types",
   subjects: "Subjects",
@@ -50,6 +52,7 @@ enum PCSClass {
  *
  * See https://taxonomy.candid.org/organization-type for more information.
  */
+@Versioning.added(CommonGrants.Versions.v0_2)
 model PCSOrgType extends PCSTerm {
   /** The PCS term for the organization type. */
   class: PCSClass.orgTypes;
@@ -59,6 +62,7 @@ model PCSOrgType extends PCSTerm {
  *
  * See https://taxonomy.candid.org/subjects for more information.
  */
+@Versioning.added(CommonGrants.Versions.v0_2)
 model PCSSubject extends PCSTerm {
   /** The PCS term for the subject. */
   class: PCSClass.subjects;
@@ -68,6 +72,7 @@ model PCSSubject extends PCSTerm {
  *
  * See https://taxonomy.candid.org/populations for more information.
  */
+@Versioning.added(CommonGrants.Versions.v0_2)
 model PCSPopulation extends PCSTerm {
   /** The PCS term for the population. */
   class: PCSClass.populationGroups;
@@ -77,6 +82,7 @@ model PCSPopulation extends PCSTerm {
  *
  * See https://taxonomy.candid.org/support-strategies for more information.
  */
+@Versioning.added(CommonGrants.Versions.v0_2)
 model PCSSupportStrategy extends PCSTerm {
   /** The PCS term for the support strategy. */
   class: PCSClass.supportStrategies;
@@ -86,6 +92,7 @@ model PCSSupportStrategy extends PCSTerm {
  *
  * See https://taxonomy.candid.org/transaction-types for more information.
  */
+@Versioning.added(CommonGrants.Versions.v0_2)
 model PCSTransactionType extends PCSTerm {
   /** The PCS term for the transaction type. */
   class: PCSClass.transactionTypes;

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

@@ -0,0 +1,98 @@
+namespace CommonGrants.Models;
+
+// #########################################################
+// ApplicantType
+// #########################################################
+
+/** The type of applicant eligible to apply for funding */
+@example(Examples.ApplicantType.organization)
+@example(Examples.ApplicantType.individual)
+@Versioning.added(CommonGrants.Versions.v0_2)
+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 */
+@Versioning.added(CommonGrants.Versions.v0_2)
+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,8 @@
 namespace CommonGrants.Models;
 
+/** The base model for an application to a competition for a funding opportunity */
+@example(Examples.Application.applicationBase)
+@Versioning.added(CommonGrants.Versions.v0_2)
 model ApplicationBase {
   /** The unique identifier for the application */
   id: Types.uuid;
@@ -19,6 +22,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 +36,17 @@ model ApplicationBase {
 // AppStatus
 // #########################################################
 
-/** The status of the application. */
+/** The status of the application */
 @example(Examples.Application.submittedStatus)
+@Versioning.added(CommonGrants.Versions.v0_2)
 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 +54,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 +73,15 @@ enum AppStatusOptions {
 // ApplicationFormResponse
 // #########################################################
 
-model AppFormResponse extends FormResponseBase {
+/** The model for a form response included in an application */
+@example(Examples.Application.formResponse)
+@Versioning.added(CommonGrants.Versions.v0_2)
+model AppFormResponse {
   /** The unique identifier for the application */
   applicationId: Types.uuid;
+
+  /** Includes all the fields from the FormResponseBase model */
+  ...FormResponseBase;
 }
 
 // #########################################################
@@ -84,9 +94,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

@@ -7,6 +7,7 @@ namespace CommonGrants.Models;
  * distinct application period and set of application forms.
  */
 @example(Examples.Competition.competition)
+@Versioning.added(CommonGrants.Versions.v0_2)
 model CompetitionBase {
   /** Globally unique id for the competition */
   id: Types.uuid;
@@ -21,17 +22,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 +50,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 +64,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 +86,7 @@ model CompetitionForms {
   forms: Record<Models.Form>;
 
   /** The validation rules for the competition forms */
-  validation: Record<unknown>;
+  validation?: Record<unknown>;
 }
 
 // #########################################################
@@ -87,10 +96,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>;