@common-grants/core 0.2.4 → 0.3.0

package/lib/api.tsp

@@ -31,9 +31,17 @@ using Versioning;
   }
 )
 @tagMetadata("Forms", #{ description: "Endpoints related to forms" })
+@tagMetadata(
+  "Application Reviews",
+  #{
+    description: "Endpoints related to reviewing applications for a given competition",
+  }
+)
 @tagMetadata(
   "Applications",
-  #{ description: "Endpoints related to applications for a given competition" }
+  #{
+    description: "Endpoints related to submitting applications for a given competition",
+  }
 )
 @tagMetadata(
   "Competitions",
@@ -122,6 +130,14 @@ namespace Applications {
 
   @added(Versions.v0_2)
   op submitApplication is ApplicationRouter.submitApplication;
+
+  // ################################
+  // Search applications
+  // ################################
+
+  @added(Versions.v0_3)
+  @tag("Application Reviews")
+  op searchApplications is ApplicationRouter.searchApplications;
 }
 
 // #########################################################

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

@@ -5,6 +5,7 @@ namespace CommonGrants.Fields;
 // ########################################
 
 /** The set of JSON schema types supported by a custom field */
+@Versioning.added(CommonGrants.Versions.v0_1)
 enum CustomFieldType {
   string,
   number,
@@ -44,6 +45,7 @@ enum CustomFieldType {
   #{ title: "Array field for eligibility types" }
 )
 @doc("A custom field on a model")
+@Versioning.added(CommonGrants.Versions.v0_1)
 model CustomField {
   /** Name of the custom field */
   name: string;

package/lib/core/fields/event.tsp

@@ -14,6 +14,7 @@ using Types;
  * - dateRange: A period of time with a start and end date
  * - other: Other event type (e.g., a recurring event)
  */
+@Versioning.added(CommonGrants.Versions.v0_1)
 enum EventType {
   /** A single date with no time */
   singleDate,
@@ -30,6 +31,7 @@ enum EventType {
 // ########################################
 
 /** Union of all event types */
+@Versioning.added(CommonGrants.Versions.v0_1)
 union Event {
   /** A single date event */
   singleDate: SingleDateEvent,
@@ -47,6 +49,7 @@ union Event {
 
 /** Base model for all events */
 @discriminator("eventType")
+@Versioning.added(CommonGrants.Versions.v0_1)
 model EventBase {
   /** Human-readable name of the event (e.g., 'Application posted', 'Question deadline') */
   name: string;
@@ -65,6 +68,7 @@ model EventBase {
 /** Description of an event that has a date (and possible time) associated with it */
 @example(Examples.Event.postedDate, #{ title: "Opportunity posted date" })
 @example(Examples.Event.closeDate, #{ title: "Opportunity close date" })
+@Versioning.added(CommonGrants.Versions.v0_1)
 model SingleDateEvent extends EventBase {
   /** Type of event */
   eventType: EventType.singleDate;
@@ -83,6 +87,7 @@ model SingleDateEvent extends EventBase {
 /** Description of an event that has a start and end date (and possible time) associated with it */
 @example(Examples.Event.performancePeriod, #{ title: "Period of performance" })
 @example(Examples.Event.applicationPeriod, #{ title: "Application period" })
+@Versioning.added(CommonGrants.Versions.v0_1)
 model DateRangeEvent extends EventBase {
   /** Type of event */
   eventType: EventType.dateRange;
@@ -106,6 +111,7 @@ model DateRangeEvent extends EventBase {
 
 /** Description of an event that is not a single date or date range */
 @example(Examples.Event.infoSessions, #{ title: "Info sessions" })
+@Versioning.added(CommonGrants.Versions.v0_1)
 model OtherEvent extends EventBase {
   /** Type of event */
   eventType: EventType.other;
@@ -134,7 +140,7 @@ namespace Examples.Event {
 
   /** An example of an opportunity posted date without a specific time */
   const postedDate = #{
-    name: "Application posted date",
+    name: "Opportunity posted date",
     eventType: EventType.singleDate,
     date: isoDate.fromISO("2024-01-15"),
     description: "Opportunity is posted publicly",

package/lib/core/fields/file.tsp

@@ -47,4 +47,24 @@ namespace Examples.File {
     createdAt: utcDateTime.fromISO("2025-01-01T17:01:01"),
     lastModifiedAt: utcDateTime.fromISO("2025-01-02T17:30:00"),
   };
+
+  const excelFile = #{
+    downloadUrl: "https://example.com/excel.xlsx",
+    name: "excel.xlsx",
+    description: "The excel file for the application",
+    sizeInBytes: 1000,
+    mimeType: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    createdAt: utcDateTime.fromISO("2025-01-01T17:01:01"),
+    lastModifiedAt: utcDateTime.fromISO("2025-01-02T17:30:00"),
+  };
+
+  const zipFile = #{
+    downloadUrl: "https://example.com/application.zip",
+    name: "application.zip",
+    description: "The zip file for the application",
+    sizeInBytes: 50000,
+    mimeType: "application/zip",
+    createdAt: utcDateTime.fromISO("2025-01-01T17:01:01"),
+    lastModifiedAt: utcDateTime.fromISO("2025-01-02T17:30:00"),
+  };
 }

package/lib/core/fields/metadata.tsp

@@ -19,6 +19,7 @@ namespace CommonGrants.Fields;
  * ```
  * */
 @example(Examples.Metadata.system)
+@Versioning.added(CommonGrants.Versions.v0_1)
 model SystemMetadata {
   /** The timestamp (in UTC) at which the record was created. */
   @visibility(Lifecycle.Read)

package/lib/core/fields/money.tsp

@@ -18,6 +18,7 @@ using Types;
   Examples.Money.usdNegative,
   #{ title: "A negative amount of US dollars and cents" }
 )
+@Versioning.added(CommonGrants.Versions.v0_1)
 model Money {
   /** The amount of money */
   amount: decimalString;

package/lib/core/fields/phone.tsp

@@ -3,6 +3,7 @@ namespace CommonGrants.Fields;
 /** A phone number. */
 @example(Examples.Phone.mobile)
 @example(Examples.Phone.withExtension)
+@Versioning.added(CommonGrants.Versions.v0_2)
 model Phone {
   /** The international country code (e.g., "+1" for US/Canada). */
   @pattern("^\\+[1-9][0-9]{0,3}$")
@@ -25,6 +26,7 @@ model Phone {
 /** A collection of phone numbers for a person. */
 @example(Examples.Phone.personalCollection)
 @example(Examples.Phone.orgCollection)
+@Versioning.added(CommonGrants.Versions.v0_2)
 model PhoneCollection {
   /** The person's primary phone number. */
   primary: Fields.Phone;

package/lib/core/filters/base.tsp

@@ -5,6 +5,7 @@ namespace CommonGrants.Filters;
 // ############################################################################
 
 /** Operators that filter a field based on an exact match to a value */
+@Versioning.added(CommonGrants.Versions.v0_1)
 enum EquivalenceOperators {
   /** Equal to a value */
   eq,
@@ -14,6 +15,7 @@ enum EquivalenceOperators {
 }
 
 /** Operators that filter a field based on a comparison to a value */
+@Versioning.added(CommonGrants.Versions.v0_1)
 enum ComparisonOperators {
   /** Greater than a value */
   gt,
@@ -29,6 +31,7 @@ enum ComparisonOperators {
 }
 
 /** Operators that filter a field based on an array of values */
+@Versioning.added(CommonGrants.Versions.v0_1)
 enum ArrayOperators {
   /** In an array of values */
   in,
@@ -38,6 +41,7 @@ enum ArrayOperators {
 }
 
 /** Operators that filter a field based on a string value */
+@Versioning.added(CommonGrants.Versions.v0_1)
 enum StringOperators {
   /** Like */
   like,
@@ -47,6 +51,7 @@ enum StringOperators {
 }
 
 /** Operators that filter a field based on a range of values */
+@Versioning.added(CommonGrants.Versions.v0_1)
 enum RangeOperators {
   /** Between a range of values */
   between,
@@ -55,6 +60,7 @@ enum RangeOperators {
   outside,
 }
 
+@Versioning.added(CommonGrants.Versions.v0_1)
 enum AllOperators {
   ...EquivalenceOperators,
   ...ComparisonOperators,
@@ -68,6 +74,7 @@ enum AllOperators {
 // ############################################################################
 
 /** A base filter model that can be used to create more specific filter models */
+@Versioning.added(CommonGrants.Versions.v0_1)
 model DefaultFilter {
   /** The operator to apply to the filter value */
   operator:

package/lib/core/filters/date.tsp

@@ -8,6 +8,7 @@ namespace CommonGrants.Filters;
 // ############################################################################
 
 /** Filters by comparing a field to a date value */
+@Versioning.added(CommonGrants.Versions.v0_1)
 model DateComparisonFilter {
   /** The operator to apply to the filter value */
   operator: ComparisonOperators;
@@ -22,6 +23,7 @@ model DateComparisonFilter {
 // ############################################################################
 
 /** Filters by comparing a field to a range of date values */
+@Versioning.added(CommonGrants.Versions.v0_1)
 model DateRangeFilter {
   /** The operator to apply to the filter value */
   operator: RangeOperators;

package/lib/core/filters/money.tsp

@@ -8,6 +8,7 @@ namespace CommonGrants.Filters;
 // ############################################################################
 
 /** Filters by comparing a field to a monetary value */
+@Versioning.added(CommonGrants.Versions.v0_1)
 model MoneyComparisonFilter {
   /** The operator to apply to the filter value */
   operator: ComparisonOperators;
@@ -22,6 +23,7 @@ model MoneyComparisonFilter {
 // ############################################################################
 
 /** Filters by comparing a field to a range of monetary values */
+@Versioning.added(CommonGrants.Versions.v0_1)
 model MoneyRangeFilter {
   /** The operator to apply to the filter value */
   operator: RangeOperators;

package/lib/core/filters/numeric.tsp

@@ -9,9 +9,11 @@ namespace CommonGrants.Filters;
 // ############################################################################
 
 /** Filters by comparing a field to a numeric value */
+@Versioning.added(CommonGrants.Versions.v0_1)
 model NumberComparisonFilter {
   /** The comparison operator to apply to the filter value */
-  operator: ComparisonOperators;
+  @Versioning.typeChangedFrom(CommonGrants.Versions.v0_3, ComparisonOperators)
+  operator: ComparisonOperators | EquivalenceOperators;
 
   /** The value to use for the filter operation */
   @example(1000)
@@ -23,6 +25,7 @@ model NumberComparisonFilter {
 // ############################################################################
 
 /** Filters by comparing a field to a numeric range */
+@Versioning.added(CommonGrants.Versions.v0_1)
 model NumberRangeFilter {
   /** The operator to apply to the filter value */
   operator: RangeOperators;
@@ -40,6 +43,7 @@ model NumberRangeFilter {
 // ############################################################################
 
 /** Filters by comparing a field to an array of numeric values */
+@Versioning.added(CommonGrants.Versions.v0_1)
 model NumberArrayFilter {
   /** The operator to apply to the filter value */
   operator: ArrayOperators;

package/lib/core/filters/string.tsp

@@ -7,6 +7,7 @@ namespace CommonGrants.Filters;
 // ############################################################################
 
 /** A filter that applies a comparison to a string value */
+@Versioning.added(CommonGrants.Versions.v0_1)
 model StringComparisonFilter {
   /** The operator to apply to the filter value */
   operator: EquivalenceOperators | StringOperators;
@@ -21,6 +22,7 @@ model StringComparisonFilter {
 // ############################################################################
 
 /** Filters by comparing a field to an array of string values */
+@Versioning.added(CommonGrants.Versions.v0_1)
 model StringArrayFilter {
   /** The operator to apply to the filter value */
   operator: ArrayOperators;

package/lib/core/models/application.tsp

@@ -13,6 +13,10 @@ model ApplicationBase {
   /** The unique identifier for the competition */
   competitionId: Types.uuid;
 
+  /** The unique identifier for the opportunity being applied to */
+  @Versioning.added(CommonGrants.Versions.v0_3)
+  opportunityId: Types.uuid;
+
   /** The form responses for the application */
   formResponses: Record<AppFormResponse>;
 
@@ -61,6 +65,7 @@ model AppStatus {
  * - `rejected`: The application has been rejected
  * - `custom`: A custom status
  */
+@Versioning.added(CommonGrants.Versions.v0_1)
 enum AppStatusOptions {
   inProgress,
   submitted,
@@ -84,6 +89,79 @@ model AppFormResponse {
   ...FormResponseBase;
 }
 
+// #########################################################
+// AppFilters
+// #########################################################
+
+/** Filters to apply when searching for applications */
+@Versioning.added(CommonGrants.Versions.v0_3)
+model AppFilters {
+  /** The default filters to apply to the search */
+  ...AppDefaultFilters;
+
+  /** Additional implementation-defined filters to apply to the search */
+  customFilters?: Record<Filters.DefaultFilter>;
+}
+
+/** The standard set of filters supported for application searches */
+@Versioning.added(CommonGrants.Versions.v0_3)
+model AppDefaultFilters extends Record<Filters.DefaultFilter> {
+  /** `opportunityId` matches one of the following values */
+  @example(#{
+    operator: Filters.ArrayOperators.in,
+    value: #["ad3b469a-d89a-42d3-c439-6c1234567890"],
+  })
+  opportunityId?: Filters.StringArrayFilter;
+
+  /** `competitionId` matches one of the following values */
+  @example(#{
+    operator: Filters.ArrayOperators.in,
+    value: #["123e4567-e89b-12d3-a456-426614174000"],
+  })
+  competitionId?: Filters.StringArrayFilter;
+
+  /** `submittedAt` is between the given range */
+  @example(#{
+    operator: Filters.RangeOperators.between,
+    value: #{
+      min: Types.isoDate.fromISO("2025-01-01"),
+      max: Types.isoDate.fromISO("2025-01-30"),
+    },
+  })
+  submittedAtRange?: Filters.DateRangeFilter;
+
+  /** `status.value` matches one of the following values */
+  @example(#{
+    operator: Filters.ArrayOperators.in,
+    value: #["submitted", "accepted"],
+  })
+  status?: Filters.StringArrayFilter;
+}
+
+// #########################################################
+// AppSorting
+// #########################################################
+
+/** The fields that can be used to sort applications */
+@Versioning.added(CommonGrants.Versions.v0_3)
+enum AppSortBy {
+  lastModifiedAt,
+  createdAt,
+  submittedAt,
+  status: "status.value",
+  opportunityId,
+  competitionId,
+  custom,
+}
+
+/** Sorting parameters for applications */
+@Versioning.added(CommonGrants.Versions.v0_3)
+model AppSorting extends Sorting.SortBodyParams {
+  /** The field to sort by */
+  @example(AppSortBy.opportunityId)
+  sortBy: AppSortBy;
+}
+
 // #########################################################
 // Examples
 // #########################################################
@@ -110,14 +188,36 @@ namespace Examples.Application {
     ...Examples.FormResponse.formResponse,
   };
 
+  const attachmentsCustomField = #{
+    name: "attachments",
+    fieldType: Fields.CustomFieldType.object,
+    value: #{
+      contacts: Fields.Examples.File.pdfFile,
+      budget: Fields.Examples.File.excelFile,
+    },
+    description: "The attachments for the application",
+  };
+
+  const applicationZipFileCustomField = #{
+    name: "applicationZipFile",
+    fieldType: Fields.CustomFieldType.object,
+    value: Fields.Examples.File.zipFile,
+    description: "The zip file for the application",
+  };
+
   const applicationBase = #{
     id: "123e4567-e89b-12d3-a456-426614174000",
     name: "My Application",
     competitionId: "123e4567-e89b-12d3-a456-426614174000",
+    opportunityId: "ad3b469a-d89a-42d3-c439-6c1234567890",
     formResponses: #{ formA: formResponse },
     status: inProgressStatus,
     submittedAt: null,
     createdAt: utcDateTime.fromISO("2021-01-01T00:00:00Z"),
     lastModifiedAt: utcDateTime.fromISO("2021-01-01T00:00:00Z"),
+    customFields: #{
+      attachments: attachmentsCustomField,
+      applicationZipFile: applicationZipFileCustomField,
+    },
   };
 }

package/lib/core/models/competition.tsp

@@ -49,6 +49,7 @@ model CompetitionBase {
 
 /** The status of the competition */
 @example(Examples.Competition.status)
+@Versioning.added(CommonGrants.Versions.v0_2)
 model CompetitionStatus {
   /** The status of the competition, from a predefined set of options */
   value: CompetitionStatusOptions;
@@ -69,6 +70,7 @@ model CompetitionStatus {
  * - `closed`: The competition is no longer accepting applications
  * - `custom`: A custom status
  */
+@Versioning.added(CommonGrants.Versions.v0_2)
 enum CompetitionStatusOptions {
   open,
   closed,
@@ -81,9 +83,10 @@ enum CompetitionStatusOptions {
 
 /** Set of forms that need to be completed to apply to the competition. */
 @example(Examples.Competition.forms)
+@Versioning.added(CommonGrants.Versions.v0_2)
 model CompetitionForms {
   /** The forms for the competition */
-  forms: Record<Models.Form>;
+  forms: Record<Models.FormBase>;
 
   /** The validation rules for the competition forms */
   validation?: Record<unknown>;
@@ -93,7 +96,9 @@ model CompetitionForms {
 // CompetitionTimeline
 // #########################################################
 
+/** Key dates in the competition's timeline. */
 @example(Examples.Competition.keyDates)
+@Versioning.added(CommonGrants.Versions.v0_2)
 model CompetitionTimeline {
   /** The start date of the competition */
   openDate?: Fields.Event;

package/lib/core/models/form.tsp

@@ -9,7 +9,8 @@ namespace CommonGrants.Models;
 /** A form for collecting data from a user. */
 @example(Examples.Form.form)
 @Versioning.added(CommonGrants.Versions.v0_2)
-model Form {
+@Versioning.renamedFrom(CommonGrants.Versions.v0_3, "Form")
+model FormBase {
   /** The form's unique identifier. */
   id: Types.uuid;
 
@@ -19,6 +20,9 @@ model Form {
   /** The form's description. */
   description?: string;
 
+  @Versioning.added(CommonGrants.Versions.v0_3)
+  version?: string;
+
   /** The form's instructions. */
   instructions?: string | Fields.File[];
 
@@ -36,6 +40,9 @@ model Form {
 
   /** Custom attributes about the form itself, not custom fields within the form. */
   customFields?: Record<Fields.CustomField>;
+
+  /** The system metadata for the form. */
+  ...Fields.SystemMetadata;
 }
 
 // #########################################################
@@ -74,6 +81,8 @@ namespace Examples.Form {
     uiSchema: uiSchema,
     mappingToCommonGrants: mappingToCommonGrants,
     mappingFromCommonGrants: mappingFromCommonGrants,
+    createdAt: utcDateTime.fromISO("2025-01-01T17:01:01"),
+    lastModifiedAt: utcDateTime.fromISO("2025-01-02T17:30:00"),
   };
 
   const formSchema = #{

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

@@ -40,6 +40,7 @@ using Types;
  * ```
  */
 @doc("A funding opportunity")
+@Versioning.added(CommonGrants.Versions.v0_1)
 model OpportunityBase {
   /** Globally unique id for the opportunity */
   @visibility(Lifecycle.Read)

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

@@ -19,6 +19,7 @@ using Fields;
   #{ title: "Total funding limit but no award range" }
 )
 @example(Examples.Funding.allFields, #{ title: "All fields defined" })
+@Versioning.added(CommonGrants.Versions.v0_1)
 model OppFunding {
   /** Details about the funding available for this opportunity that don't fit other fields */
   details?: string;

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

@@ -8,6 +8,7 @@ namespace CommonGrants.Models;
 // ############################################################################
 
 /** Filters to apply when searching for opportunities */
+@Versioning.added(CommonGrants.Versions.v0_1)
 model OppFilters {
   /** The default filters to apply to the search */
   ...OppDefaultFilters;
@@ -17,6 +18,7 @@ model OppFilters {
 }
 
 /** The standard set of filters supported for opportunity searches */
+@Versioning.added(CommonGrants.Versions.v0_1)
 model OppDefaultFilters extends Record<Filters.DefaultFilter> {
   /** `status.value` matches one of the following values */
   @example(#{
@@ -82,6 +84,7 @@ model OppDefaultFilters extends Record<Filters.DefaultFilter> {
 // Sorting models
 // ############################################################################
 
+@Versioning.added(CommonGrants.Versions.v0_1)
 enum OppSortBy {
   lastModifiedAt,
   createdAt,
@@ -95,6 +98,7 @@ enum OppSortBy {
   custom,
 }
 
+@Versioning.added(CommonGrants.Versions.v0_1)
 model OppSorting extends Sorting.SortBodyParams {
   /** The field to sort by */
   @example(OppSortBy.lastModifiedAt)

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

@@ -10,6 +10,7 @@ namespace CommonGrants.Models;
  * - `closed`: The opportunity is no longer accepting applications
  * - `custom`: A custom status
  */
+@Versioning.added(CommonGrants.Versions.v0_1)
 enum OppStatusOptions {
   forecasted,
   open,
@@ -24,6 +25,7 @@ enum OppStatusOptions {
 /** The status of the opportunity */
 @example(Examples.OppStatus.custom)
 @example(Examples.OppStatus.default)
+@Versioning.added(CommonGrants.Versions.v0_1)
 model OppStatus {
   /** The status of the opportunity, from a predefined set of options */
   value: OppStatusOptions;

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

@@ -12,6 +12,7 @@ using Types;
 
 /** Key dates and events in the opportunity's timeline, such as when the opportunity is posted and closes */
 @example(Examples.Timeline.opportunity)
+@Versioning.added(CommonGrants.Versions.v0_1)
 model OppTimeline {
   /** The date (and time) at which the opportunity is posted */
   postDate?: Event;

package/lib/core/models/proposal.tsp

@@ -54,6 +54,7 @@ model ProposalOpportunity {
 // ProjectTimeline
 // #########################################################
 
+/** Key dates for the project. */
 @Versioning.added(CommonGrants.Versions.v0_2)
 model ProjectTimeline {
   /** The start date of the period for which the funding is requested. */
@@ -73,6 +74,7 @@ model ProjectTimeline {
 // ProjectContacts
 // #########################################################
 
+/** The points of contact for the proposal. */
 @Versioning.added(CommonGrants.Versions.v0_2)
 model ProposalContacts {
   /** The primary point of contact for the proposal. */
@@ -86,6 +88,7 @@ model ProposalContacts {
 // ProposalOrgs
 // #########################################################
 
+/** The organizations that are requesting funding or supporting the proposal. */
 @Versioning.added(CommonGrants.Versions.v0_2)
 model ProposalOrgs {
   /** The primary organization that is requesting funding. */

package/lib/core/pagination.tsp

@@ -8,6 +8,7 @@ using TypeSpec.JsonSchema;
 namespace CommonGrants.Pagination;
 
 /** Query parameters for paginated routes */
+@Versioning.added(CommonGrants.Versions.v0_1)
 model PaginatedQueryParams {
   /** The page to return */
   @query
@@ -23,6 +24,7 @@ model PaginatedQueryParams {
 }
 
 /** Body parameters for paginated routes */
+@Versioning.added(CommonGrants.Versions.v0_1)
 model PaginatedBodyParams {
   /** The page to return */
   @pageIndex
@@ -36,6 +38,7 @@ model PaginatedBodyParams {
 }
 
 /** Details about the paginated results */
+@Versioning.added(CommonGrants.Versions.v0_1)
 model PaginatedResultsInfo {
   /** Current page number (indexing starts at 1) */
   @example(1)

package/lib/core/responses/error.tsp

@@ -14,6 +14,7 @@ namespace CommonGrants.Responses;
  */
 @error
 @doc("A non-2xx response schema")
+@Versioning.added(CommonGrants.Versions.v0_1)
 model Error {
   @example(400)
   status: int32;

package/lib/core/responses/success.tsp

@@ -8,6 +8,7 @@ namespace CommonGrants.Responses;
 // Default success response
 // ############################################################################
 
+@Versioning.added(CommonGrants.Versions.v0_1)
 model Success {
   @example(200)
   status: int32;
@@ -37,6 +38,7 @@ model Success {
  * ```
  */
 @doc("A 200 response with data")
+@Versioning.added(CommonGrants.Versions.v0_1)
 model Ok<T> extends Success {
   // Inherit the 200 status code
   ...Http.OkResponse;
@@ -66,6 +68,7 @@ model Ok<T> extends Success {
  * ```
  */
 @doc("A 200 response with a paginated list of items")
+@Versioning.added(CommonGrants.Versions.v0_1)
 model Paginated<T> extends Success {
   // Inherit the 200 status code
   ...Http.OkResponse;
@@ -98,6 +101,8 @@ model Paginated<T> extends Success {
  * alias CustomModelSortedResponse = Responses.Sorted<CustomModel>;
  * ```
  */
+@doc("A paginated list of items with a sort order")
+@Versioning.added(CommonGrants.Versions.v0_1)
 model Sorted<T> {
   // Inherit the properties of the Paginated response
   ...Paginated<T>;
@@ -132,6 +137,8 @@ model Sorted<T> {
  * alias CustomModelFilteredResponse = Responses.Filtered<CustomModel, CustomFilter>;
  * ```
  */
+@doc("A paginated list of items with a filter")
+@Versioning.added(CommonGrants.Versions.v0_1)
 model Filtered<ItemsT, FilterT> extends Success {
   // Inherit the properties of the Sorted response
   ...Sorted<ItemsT>;
@@ -153,6 +160,7 @@ model Filtered<ItemsT, FilterT> extends Success {
  *
  * @template T The schema for the value of the `"data"` property in this response
  */
+@Versioning.added(CommonGrants.Versions.v0_1)
 model Created<T> extends Success {
   // Inherit the 201 status code
   ...Http.CreatedResponse;

package/lib/core/routes/applications.tsp

@@ -63,4 +63,20 @@ interface Applications {
     | Responses.ApplicationSubmissionError
     | Responses.NotFound
     | Responses.Unauthorized;
+
+  // ###############################
+  // Search applications
+  // ###############################
+
+  @summary("Search applications")
+  @doc("Search for applications. Note: The search results for a given query will depend on the scopes attached to the API token used to make the request.")
+  @post
+  @route("/search")
+  searchApplications(
+    /** The filters to apply to the search */
+    @query filters: Models.AppFilters,
+
+    /** The sorting to apply to the search */
+    @query sorting: Models.AppSorting,
+  ): Responses.Filtered<Models.ApplicationBase, Models.AppFilters>;
 }

package/lib/core/routes/forms.tsp

@@ -22,7 +22,9 @@ interface Forms {
   @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>;
+  list(
+    ...Pagination.PaginatedQueryParams,
+  ): Responses.Paginated<Models.FormBase>;
 
   // ###############################
   // View form details
@@ -34,5 +36,5 @@ interface Forms {
   read(
     /** The ID of the form to view */
     @path formId: Types.uuid,
-  ): Responses.Ok<Models.Form>;
+  ): Responses.Ok<Models.FormBase>;
 }

package/lib/core/sorting.tsp

@@ -18,12 +18,14 @@ using TypeSpec.JsonSchema;
 @jsonSchema
 namespace CommonGrants.Sorting;
 
+@Versioning.added(CommonGrants.Versions.v0_1)
 enum SortOrder {
   asc,
   desc,
 }
 
 /** Query parameters for sorting */
+@Versioning.added(CommonGrants.Versions.v0_1)
 model SortQueryParams {
   /** The field to sort by */
   @query
@@ -42,6 +44,7 @@ model SortQueryParams {
 }
 
 /** Sorting parameters included in the request body */
+@Versioning.added(CommonGrants.Versions.v0_1)
 model SortBodyParams {
   /** The field to sort by */
   @example("lastModifiedAt")
@@ -57,6 +60,7 @@ model SortBodyParams {
 }
 
 /** Information about the sort order of the items returned */
+@Versioning.added(CommonGrants.Versions.v0_1)
 model SortedResultsInfo {
   /** The field results are sorted by, or "custom" if an implementation-defined sort key is used */
   @example("lastModifiedAt")

package/lib/core/types.tsp

@@ -28,6 +28,7 @@ namespace CommonGrants.Types;
 /** A universally unique identifier */
 @example("30a12e5e-5940-4c08-921c-17a8960fcf4b")
 @format("uuid")
+@Versioning.added(CommonGrants.Versions.v0_1)
 scalar uuid extends string;
 
 /** An email address */
@@ -67,6 +68,7 @@ scalar duns extends string;
 @example("100", #{ title: "Scale 0" })
 @example("100.5", #{ title: "Scale 1" })
 @example("-100.5", #{ title: "Negative, scale 2" })
+@Versioning.added(CommonGrants.Versions.v0_1)
 scalar decimalString extends string;
 
 // ########################################
@@ -75,10 +77,12 @@ scalar decimalString extends string;
 
 /** A time on a clock, without a timezone, in ISO 8601 format HH:mm:ss */
 @example(isoTime.fromISO("17:00:00"))
+@Versioning.added(CommonGrants.Versions.v0_1)
 scalar isoTime extends plainTime;
 
 /** A date on a calendar in ISO 8601 format YYYY-MM-DD */
 @example(isoDate.fromISO("2025-01-01"))
+@Versioning.added(CommonGrants.Versions.v0_1)
 scalar isoDate extends plainDate;
 
 /** A calendar year */

package/lib/main.tsp

@@ -18,4 +18,5 @@ namespace CommonGrants;
 enum Versions {
   v0_1: "0.1.0",
   v0_2: "0.2.0",
+  v0_3: "0.3.0",
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@common-grants/core",
-  "version": "0.2.4",
+  "version": "0.3.0",
   "description": "TypeSpec library for defining grant opportunity data models and APIs",
   "type": "module",
   "main": "dist/src/index.js",
@@ -49,7 +49,7 @@
   },
   "devDependencies": {
     "@eslint/js": "^9.18.0",
-    "@types/node": "^20.10.6",
+    "@types/node": "^20.19.23",
     "eslint": "^9.18.0",
     "globals": "^15.14.0",
     "prettier": "^3.4.2",